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e The Conditional Assembly Language 


The “ordinary” assembly language is translated by the Assembler into the machine lan- 
guage of the System/360/370/390 processors, for eventual execution by such a processor. 
The “conditional” assembly language is interpreted and executed by the Assembler at 
assembly time to tailor, select, and create desired sequences of statements. 


Conditional Assembly Language 


Z e Ordinary vs. Conditional assembly languages: 
| - ordinary: 
— translated by the Assembler into machine language 
— eventually executed on a System/360/370/390 processor 
- conditional: 
— interpreted and executed by the Assembler at assembly time 
— tailors, selects, and creates sequences of statements 


Conditional Assembly Language: 
- general purpose (if a bit primitive) 
— data types and structures; variables; expressions and operators; assignments; 
conditional and unconditional branches, built-in functions; I/O, subroutines. 
Characteristic uses of conditional-assembly symbols: 
- variable symbols: evaluation and substitution 
—- sequence symbols: selection 
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Though primitive in many respects, the conditional assembly language has most of the basic 
elements of a general purpose programming language: data types and structures, variables, 
expressions and operators, assignments, conditional and unconditional branches, some 
built-in functions, simple forms of I/O, and subroutines. 


The distinctive feature of the conditional assembly language is the introduction of two new 
classes of symbols: 


e variable symbols are used for evaluation and substitution 


e sequence symbols are used for selection among alternative actions. 


Just as “normal” or “ordinary” assembly deals with ordinary symbols — assigning values to 
symbols and using those values to evaluate various kinds of expressions — the conditional 
assembly language uses variable and sequence symbols. 
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Evaluation, Substitution, and Selection 


ed 


e Three key concepts of conditional assembly: 


1. Evaluation 


- Assigns values to variable symbols, based on the results of computing complex 
expressions. 


Substitution 


- You write the name of a variable symbol where the Assembler is to substitute the 
value of the variable symbol. 


- Permits modification of the “ordinary assembly language" text stream. 
Selection 


- Use sequence symbols to alter the normal, sequential flow of statement 
processing. 


- Selects different sets of statements for further processing. 
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Evaluation, Substitution, and Selection 


2 


There are three key concepts in the conditional assembly language: 


e evaluation 
e substitution 
° selection 


Evaluation allows you to assign values to variable symbols based on the results of com- 
puting complex expressions. 


Substitution is achieved by writing the name of a special symbol, a variable symbol, in a 
context that the Assembler will recognize as requiring substitution of the va/ue of the vari- 
able symbol. This permits modification of the “ordinary assembly language” text stream to 
be processed by the assembler. 


Selection is achieved by using sequence symbols to alter the normal, sequential flow of 


statement processing. This permits different sets of statements to be presented to the 
Assembler for further processing. 
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Variable Symbols 


¢ Written as an ordinary symbol prefixed by an ampersand (&) 
Examples: 
8A = &T time &DATE &My_ Value 


Variable symbols starting with &SYS are reserved to the Assembler 


Three variable symbol types are supported: 

- Arithmetic: values represented as 32-bit 2’s complement integers 
- Boolean: values are 0, 1 

- Character: strings of 0 to 255 EBCDIC characters 


Two scopes are supported: 


- local: known only within a fixed, bounded context; not shared across 
scopes 


- global: shared in all contexts that declare the variable as global 
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Variable Symbols 


In addition to the familiar “ordinary” symbols managed by the assembler — internal and 
external — there is also a class of variable symbols. Variable symbols obey scope rules sup- 
porting two types that roughly approximate internal and external ordinary symbols, but they 
are not retained past the end of an assembly, and do not appear in the object text produced 
by the assembly. 


Variable symbols are written just as are ordinary symbols, but with the ampersand character 
(&) prefixed. Examples of variable symbols are: 


&A &a (these two are treated identically) 
&T ime 

&DATE 

aly Value 


As indicated in these examples, variable symbols may be written in mixed-case characters; 
all appearances will be treated as being equivalent to their upper-case versions. Variable 
symbols starting with the characters &SYS are reserved to the Assembler. 


There are three types of variable symbols, corresponding to the values they may take: 


arithmetic 
The allowed values of an arithmetic variable symbol are those of 32-bit (fullword) two’s 
complement integers (i.e., between —23! and +23'!—1. (Be aware that in certain contexts, 
their values may be substituted as unsigned integers!) 


boolean 
The allowed values of a boolean variable symbol are 0 and 1. 


character 
The value of a character variable symbol may contain from 0 to 255 characters, each 
being any EBCDIC character. (A character variable symbol containing no characters is 
sometimes called a null string.) 


The Conditional Assembly Language 3 


Declaring Variable Symbols 


There are six explicit declaration statements (3 types x 2 scopes) 


[Arithmetic [Boolean [Character 
ictus LeLe 
cata ——*«G BL aie 


Examples of scalar-variable declarations: 


LCLA &),&K 
GBLB  &INIT 
LCLC &Temp_Chars 


May be subscripted, in a 1-dimensional array (positive subscripts) 
LCLA &F(15 
Flight | 
May be created, in the form &(e) (where e starts with an alphabetic 
character) 


&(B&J&K) SETA &(XY&J.2)-1 
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Declaring Variable Symbols ... 


Three forms of implicit declaration: 


1. by the Assembler (for System Variable Symbols) 
— names always begin with characters &SYS 


— most have local scope 


by appearing as symbolic parameters (dummy arguments) in a macro 
prototype statement 


- symbolic parameters always have local scope 


as local variables, if first appearance is as target of an assignment 


TT Ta ae 
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Declaration 


Variable symbols are declared in several ways: 
e explicitly, through the use of declaration statements 
e by the Assembler (these are known as System Variable Symbols) 


e implicitly, by their appearance as dummy arguments in a macro prototype statement 
(these are known as symbolic parameters, they are of character type, and are local in 
scope) 


e implicitly, as local variables, through appearing for the first time as the target of an 
assignment. 


Explicitly declared variable symbols are declared using two sets of statements that specify 
their type and scope: 
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Figure 1. Explicit Variable Symbol Declarations and Initial Values 
[Arithmetic ‘| Boolean 


LCLB 
GBLB 


These declared variables are automatically initialized by the Assembler to zero (arithmetic 
and boolean variables) or to null (zero-length) strings (character variables). 


The two scopes of variable symbols — local and global — will be discussed in greater detail 
later, in “Variable Symbol Scope Rules: Summary” on page 65. For the time being, we will 
be concerned almost entirely with local variables. 


For example, to declare the three local variable symbols &A as arithmetic, &B as boolean, and 
&C as character, we would write 


LCLA &A 
LCLB &B 
LCLC ac 


More than one variable symbol may be declared on a single statement. The ampersand 
preceding the variable symbols may be omitted in LCLx and GBLx statements, if desired. 


Variable symbols may also be subscripted: that is, you may declare a one-dimensional array 
of variable symbols all having the same name, by specifying a parenthesized integer 
expression following the name of the variable. For example, 


LCLA &F(15) 
LCLB &G(15) 
LCLC &H(15) 


would declare the three subscripted local variable symbols F, G, and H to have 15 elements. 
We will see in practice that the declared size of an array is ignored, and any valid (positive) 
subscript value is permitted. Thus, it is sufficient to declare 


LCLA &F(1) 
LCLB  &G(1) 
LCLC  &H(1) 


You can determine the maximum subscript used for a subscripted variable symbol with a 
Number attribute reference (to be discussed later, at “Macro-Instruction Argument Proper- 
ties: Number Attribute” on page 60). 


Subscripted variable symbols may appear anywhere a scalar (non-subscripted) variable 
symbol appears. 


Created variable symbols may be created “dynamically”, using characters and the values of 
other variable symbols. The general form of a created variable symbol is &(e), where e must 
(after substitutions) begin with an alphabetic character. Created variable symbols may also 
be subscripted; like other variable symbols they may be declared explicitly or implicitly. 


System variable symbols and their properties are discussed in “System (&SYS) Variable 
Symbols” on page 129. 


In the examples that follow, we will typically enclose string values in apostrophes, as in 
'String', to help make the differences clearer between strings and descriptive text. 
However, the enclosing quotes are only sometimes required by the syntax rules of a partic- 
ular statement or context. 
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Substitution 


e In appropriate contexts, a variable symbol is replaced by its value 
e¢ Example: Suppose the value of &A is 1. 
Then, the result of substituting &A in 
Constant&A DC = F'&A' 
ts 
Constantl DC F'1’ 


(This illustrates why paired ampersands are required if you want a 
single & in a character constant or self-defining term.) 


To avoid ambiguities, mark the end of a variable-symbol substitution 


with a period: Seperalru | 
Write: CONST&A.B DC C'8A.B' &A followed by ‘B' 


Not: CONST&AB DC C°SAB' &A followed by ‘'B' 7? No: &AB ! 
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Substitution 


The value of a variable symbol is used by substituting its value, converted into a character 
string if necessary, into some element of a statement. For example, if the value of &A is 1 (at 
this point, it doesn’t matter whether &A is an arithmetic, boolean, or character variable), and 
we write the following DC statement: 


Constant&A DC F'ga' 
then the resulting statement would be 

Constantl OC aa iy 
That is, at each appearance of the variable symbol &A, ifs value is substituted in place of the 
symbol. (This behavior explains why you were required to write a pair of ampersands in 
character constants and self-defining terms where you wanted a single ampersand to appear 
in the character constant or self-defining term: a single ampersand would indicate to the 


Assembler that a variable symbol is expected to appear in that position.) 


The positions where substitutable variable symbols appear, and at which substitutions are 
done, are sometimes called points of substitution. 


Suppose we need to substitute the value of &A into a character constant, such that its value 
is followed by the character 'B'. If we wrote 


CONST&AB DC C'&AB' &A followed by 'B' ?? 
the assembler has a problem: should &AB be treated as the variable symbol &AB or as the 
variable symbol &A followed by 'B'? If the assembler made the latter choice, it could never 
recognize the variable symbol &AB (nor any other symbols beginning with &A, like &ABCDEFG)! 


To eliminate such ambiguities, you should indicate the end of the variable symbol with a 
period (.). Thus, the constant should be written as 


CONST&A.B DC = C'&A.B! 8A followed by 'B' 
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giving 
CONST1IB OC C'1B! &A followed by 'B! !! 


(Note that variable symbols are not substituted in remarks fields or in comments state- 
ments.) 


While the terminating period is not required in all contexts, it is a good practice to specify it 
wherever substitution is intended. (The two places where the period most definitely js 
required are when the point of substitution is to be followed by a period or a left paren- 
thesis.) | 
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The MNOTE Statement 


¢ Useful for diagnostics, tracing, information, error messages 
e Syntax: 


MNOTE severity, ‘message text’ 


severity may be 
- any arithmetic expression of value between 0 and 255 
— omitted (if the following comma is present, severity = 1) 
— value of severity is used to determine assembly completion code 
- an asterisk; the message is treated as a comment 
— omitted (if the following comma is also omitted, treat as a comment) 


Displayed quotes and ampersands must be paired 
Examples: 


-Msg 1B MNOTE 8, 'Missing Required Operand' 

X14 MNOTE , ‘Conditional Assembly has reached point .X14' 

.Traceé MNOTE *,’Value of &&A = &A., value of &&C = °'&C.''' 
MNOTE ‘Hello World (How Original!) ' 
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The MNOTE Statement 


The “inputs” to conditional assembly activities are usually values of variable symbols, and 
ordinary statements that may or may not be affected by substitution and/or selection. Simi- 
larly, the “outputs” are normally sequences of statements on which selection and substi- 
tution have been performed. 


There is another way for the conditional assembly language to “communicate” to the 
program and the programmer, by way of the MNOTE statement. 


The MNOTE statement can be used in both “open code” and in macros to provide diagnos- 
tics, trace information, and other data in an easily readable form. By providing suitable con- 
trols, you can produce or suppress such messages easily, which facilitates debugging of 
macros and of programs with complex uses of the conditional assembly language. For 
example, a program could issue MNOTE statements like the following: 


.Msg_ 1B MNOTE 8, ‘Missing Required Operand' 
X14 MNOTE ,'Conditional Assembly has reached point .X14' 


.Trace4 MNOTE *,'Value of &8&A = 8A., value of &&C = ‘'&C.'!! 
MNOTE ‘Hello World (How Original!) ' 


The first MNOTE sets the return code for the assembly to be at least 8 (presumably, due to 
an error condition); the second could indicate that the flow of control in a conditional 
assembly has reached a particular point (and will supply a default severity code value of 1); 
the third provides information about the current values of two variable symbols; and the 
fourth illustrates the creation of a simple message. 


Any quotation marks and ampersands intended to be part of the message must be paired, 
as illustrated in the example above. 


The first two MNOTEs are treated as “error” messages, which means that they will be 


flagged in the error summary in the listing and will appear in the SYSTERM output (if the 
TERM option was specified, and the setting of the FLAG option has not suppressed them). A 
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setting of an assembly severity code is also performed. The latter two MNOTEs will be 
treated as comments, and will appear only in the listing. 


Assigning Values to Variable Symbols: SET Statements 


¢ Three assignment statements: SETA, SETB, and SETC 
- One SET statement for each type of variable symbol 
¢ General form is 
&varsym SETx expression Assigns value of expression to &varsym 


Syntax: 


&A_varsym SETA arithmetic_expression 
&B varsym SETB boolean expression 
&C_varsym SETC character_expression 


Target variable symbol may be subscripted 
- Multiple values can be assigned to successive array elements 


e Syntax: 
&Subscripted_x_varsym SETx x_expression_list 
&A(6) SETA 9,2,16 Sets &A(6)=9, &A(7)=2, &A(8)=16 
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Assigning Values to Variable Symbols: SET Statements 


Assignment of new values to variable symbols occurs in three ways, corresponding to the 
©} types of declaration. 


e Explicitly and implicitly declared variable symbols of arithmetic, boolean, and character 
type are assigned values by the SETA, SETB, and SETC statements, respectively. (Since 
the type of the assigned variable is generally known in advance, having three separate 
SET statements is somewhat redundant; it does help, however, by allowing implicit dec- 
larations.) 


¢ System variable symbols are assigned values by the Assembler (and only by the 
Assembler). They may not appear in the name field of a SETx statement. 


e Symbolic parameters have their values assigned by appearing as actual arguments in a 
macro Call statement. They may not appear in the name field of a SETx statement. 


At this point, we will discuss only assignments to declared variable symbols. 


Multiple array elements may have values assigned in a single SET statement by specifying a 
list of operand-field expressions of the proper type, separated by commas. For example: 


BA(6) SETA 9,2,10 Sets &A(6)=9, &A(7)=2, &A(8)=10 


would assign 9 to &A(6), 2 to &A(7), and 10 to &A(8). (If you wish to leave one of the array 
elements unchanged, simply omit the corresponding value from the expression list.) 


Occasionally, the three declarable types of variable symbol (arithmetic, boolean, and char- 
acter) are referred to as SETA, SETB, and SETC variables, respectively, and declarable vari- 
able symbols are referred to as SET symbols. 
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Evaluating Conditional-Assembly Expressions 


As in any programming language, it is useful to evaluate expressions involving variable | 
symbols and other terms, and to assign the results to other variable symbols. 


Evaluating and Assigning Arithmetic Expressions 


e Syntax: 
&Arithmetic_Var_Sym SETA arithmetic _expression 


Follows same evaluation rules as ordinary-assembly expressions 

- Simpler, because no relocatable terms are allowed 

Terms include: 

- arithmetic and boolean variable symbols 
self-defining terms (binary, character, decimal, hexadecimal) 
character variable symbols whose value is a self-defining term 
predefined absolute ordinary symbols 


numeric-valued attribute references 
(Count, Definition, Integer, Length, Number, Scale) 


Example: 
BA SETA &D*(2+8K) /&G+ABSSYM-C'3'+L'&PL3 
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Evaluating and Assigning Arithmetic Expressions: SETA @ 


The rules for evaluating conditional-assembly arithmetic expressions are very similar to 
those for ordinary expressions, with the added great simplification that none of the terms in 
a conditional-assembly expression may be relocatable. In addition to self-defining terms, 
predefined absolute ordinary symbols may be used as terms, as may variable symbols 
whose value can be expressed as a self-defining term (whose value in turn can be repres- 
ented as a signed 32-bit integer). 


As usual, parentheses may be used in expressions to control the order and precedence of 
evaluation. 


Numeric-valued attribute references to ordinary symbols may also be used as terms; these 
are normally attribute references to character variable symbols whose value is an ordinary 
symbol. The numeric-valued attribute references are: 


Count (K') 

Definition (D') 

Integer (I') 

Length (L') 

Number (N') - 
Scale (S') 


We will illustrate applications of attribute references later, particularly when we discuss 
macros. Attribute references may, of course, be used in “open code”. 
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Evaluating and Assigning Boolean Expressions 


e Syntax: 


&Boolean Var Sym SETB hoolean_expression 


Boolean constants: 0 (false), 1 (true) 
Boolean operators: 
- NOT (highest priority), AND, OR (lowest) 
» - Unary NOT also allowed in AND NOT, OR NOT 
Relational operators (for arithmetic and character comparisons): 
- EQ, NE, GT, GE, LT, LE 
- - Character comparisons use EBCDIC collating sequence, but: 


— Shorter string always compares LT than longer! 


- Note: cannot compare arithmetic and character expressions 
Example: 
&B SETB ((&A GT 10) AND NOT ('&X* GE ‘2')) 


July 1993 High Level Assembler Tutorial Guide 
© Copyright 1BM Corporation 1993 


Evaluating and Assigning Boolean Expressions: SETB 


Boolean expressions provide much of the conditional selection capability of the conditional 
assembly language. In practice, many boolean expressions are not assigned to boolean vari- 
able symbols; rather, they are used in AIF statements to describe a condition to control 
whether or not a conditional-assembly “branch” will or will not be taken. 


@ Boolean primaries include boolean variable symbols, the boolean constants 0 and 1, and 
(most useful) comparisons. Two types of comparison are allowed: between arithmetic 
expressions, and between character expressions (which will be described in “Evaluating and 
Assigning Character Expressions: SETC” on page 13 below). Comparisons between arith- 
metic and character terms is not allowed. 


The comparison operators are 


EQ (equal) 

NE (not equal) 

GT (greater than) 

GE (greater than or equal) 
LT (less than) 

LE (less than or equal) 


In an arithmetic relation, the usual integer comparisons are indicated. (Remember that pre- 
defined absolute ordinary symbols are allowed as arithmetic terms!) 


: N EQU 10 
RN SETA 5 
&B1  SETB (&N GT 0) &B1 is TRUE 
&B2  SETB (&N GT N) &B2 is FALSE 


For character comparisons, a test is first made on the /engths of the two comparands: if they 
are not the same length, the shorter operand is always taken to be “less than” the longer. 
Note that this may not be what you would get if you did a “hardware” comparison! The fol- 
lowing example illustrates the difference. 


('BB' GT 'AAA') is always FALSE in conditional assembly 
CLC =C'BB',=C'AAA' indicates that the first operand is "high" 
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If the character comparands are the same length, then the usual EBCDIC collating sequence 
is used for the comparison, so that 


('BB' GT 'AA') is always TRUE in conditional assembly 
The boolean operators are the usual logical operators AND, OR, and NOT; note that no 
exclusive-or (XOR) operation is provided. (This deficiency can sometimes be remedied by 
noting that 
(A XOR B) = (A OR B) - (A AND B) 
if the terms can readily be cast in the arithmetic form needed for the subtraction.) 
NOT may be used as a unary operator, as in the following: 
&Bool_var SETB (NOT ('BB' EQ 'AA')) 


which would set &Bool_var to 1, meaning TRUE. 


In a compound expression involving mixed operators, the NOT operation has highest priority; 
AND has next highest priority; and OR has lowest priority. 
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Evaluating and Assigning Character Expressions 


¢ Syntax: | | 
&Character_Var_Sym SETC character_expression 


&CVar2 SETC ‘This is the Beginning of the End’ 


All terms must be quoted, except type-attribute references 
‘ -  Type-attribute references are neither quoted nor duplicated nor combined 
~ Quoted terms may be preceded by parenthesized duplication factor 
Apostrophes and ampersands in strings must be paired 
- Apostrophes are paired internally 
. &QT SETC °°"? Value of &QT is a single apostrophe 
- Ampersands are not paired internally! 
&Amp SETC ‘'8&&' &Amp has value '&&' 
&D SETC (2)'A&&B°  &D has value ‘A&S&BA&&B' 
Warning! SETA variables are substituted without sign! 


&A SETA -5S V 
BC SETC ‘&A' &C has value '5' (not '-5'1) 
© 
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Evaluating and Assigning Character Expressions: SETC 


The major elements of character expressions are quoted strings. For example, we may 
assign values to character variable symbols using quoted strings, as follows: 


3 &CVarl  SETC 'AaBbCcDdEeFf' 
&CVar2 SETC ‘This is the Beginning of the End' 


&Digits SETC '0123456789' 
&HEX SETC '0123456789ABCDEF ' 


Type attribute references may also be used as terms in character expressions, but they 
must appear as the only term in the expression: 


&TCVarl SETC T'&CVarl 


Character-string constants in SETC expressions are quoted, and internal apostrophes and 
ampersands must be written in pairs, so that the term may be recognized correctly by the 
assembler. Thus, character strings in character (SETC) expressions look like character con- 
stants and character self-defining terms in other contexts. 


However, when the assembler determines the va/ue of a character term in a SETC 
expression, there is one key difference: while apostrophes are paired to yield a single 
internal apostrophe, ampersands are not paired to yield single internal ampersands! Thus, 
if we assign a string with a pair of ampersands, the result will still contain that pair: 


&QT SETC '!!! Value of &QT is a single apostrophe 
&Amp SETC '&&! &Amp has value ‘&&' 
: &C SETC '‘A&&B! &C has value 'A&&B' 


&D  SETC (2)'A&&B' &D has value 'A&&BA&&B' 


If the value of such a variable is substituted into an ordinary statement, then the ampersands 
will be paired to produce a single ampersand, according to the familiar rules of the Assem- 
bler Language: 
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&C SETC 'A&&B' &C has value 'A&&B' 
AandB OC c'ac.' generated constant is ‘A&B' 


If a single ampersand is required in a character expression, then a substring (described 
below) of a pair of ampersands should be used. 


One reason for this behavior is that it prevents unnecessary proliferation of ampersands. For 
example, if we had wanted to create the character string 'A&&B', a requirement for paired 
ampersands in SETC expressions would require that we write 


&C SETC ‘A&&&&B' 777 
which would clearly make the language become even more awkward. The existing rules 
represent a trade-off between inconvenience and inconsistency, in favor of greater conven- 
ience. 


Character expressions introduce two new concepts: string concatenation, and substring 
operations. 


Character Expressions: Concatenation 


¢ Concatenation indicated by juxtaposition 
e Concatenation operator is the period (.) 


&B SETC ‘°A.B' &B has value ‘A.B’ 


&C SETC ‘AB' &C has value ‘AB' 
&C SETC ‘A'.'B' &C has value ‘AB' 


&D SETC ‘&C’.'E' &D has value ‘ABE' 
&E SETC ‘&D&D' &D has value 'ABEABE' 


e Period is also used to indicate the end of a variable symbol 


&D SETC ‘&C.E‘ &D has value ‘'ABE' 


&E SETC ‘'&D.&D' &D has value 'ABEABE' 
&E SETC ‘&D..&D° &D has value 'ABE.ABE' 
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String Concatenation 


We are somewhat familiar with the notion of string concatenation from some of the earlier 
examples of substitution, where a substituted value is concatenated with the adjoining char- 
acters to create the completed string of characters. As before, the end of a variable symbol 
may be denoted with a period. The period is also used as the concatenation operator, as 
shown in the following examples: 


&C SETC ‘AB' &C has value ‘AB' 

&B SETC ‘A.B! &B has value ‘'A.B' 

&C SETC 'A'.'B! &C has value ‘AB' 

&D SETC '&C'.'E! &D has value ‘ABE' 

&D SETC '&C.E' &D has value ‘ABE’ 

&E SETC '&D&D' &D has value ‘ABEABE' 
&E SETC '&D.&D' &D has value 'ABEABE' 


&E SETC ‘'&D..&D! &D has value ‘ABE.ABE' 


14 High Level Assembler Tutorial Guide 


As these examples show, there may be more than one way to specify desired concatenation 
results. 


Character Expressions: Substrings 


¢ Substrings selected by ‘string'(start_position, span) 
&C SETC ‘ABCDE'(1,3) &C has value ‘ABC’ Lencth, 
- &C SETC ‘ABCDE'(3,3)  &C has value ‘CDE' 


—- span may be zero (substring is null) 


= &C SETC ‘ABCDE'(2,6) &C has value ‘' 


- Incorrect substring operations may cause warnings or errors 


SETC ‘ABCDE'(5,3 &C has value 'E' (and a warning) 
SETC ‘ABCDE'(6,1 &C has value '* (and a warning) 
SETC ‘ABCDE'(2,-1) &C has value (and @ warning) 
SETC ‘ABCOE'(6,2) &C has value (and an scvath 
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Substrings 


Substrings are defined by a somewhat unusual (and sometimes awkward) notation, as 


©@ follows: 


substring = 'source_string'(start_position,span) 


where start_position is the position in the source_string where the substring is to begin, and 
Span is the length of the substring to be extracted. 


To illustrate, consider the following examples: 


&C SETC ‘'ABCDE'(1,3)  &C has value ‘ABC' 
&C SETC 'ABCDE'(3,3)  &C has value ‘CDE' 
&C SETC ‘ABCDE'(5,3)  &C has value 'E' (and a warning) 


So long as the substring is entirely contained within the source_string, the results are intui- 
tive. For cases where one or another of the many possible boundary conditions would 
cause the substring not to be entirely contained within the source_string, the following rules 


apply: 
1. The length of the source_string must be between 1 and 255. 
2. The span of the substring must be between 0 and 255. 


3. If 1<start_positionslength, and 1<spanslength, and start_position+ span<length + 1, 
- then a normal substring will be extracted. 


4. If start_position<0, then the assembler will issue an error message, and the substring 
will be set to null. 


5. If start_position>length, then the assembler will issue a warning message, and the sub- 
string will be set to null. 


6. If span=O, then the substring will be set to null. No error message will be issued. 
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7. If span<0, then the assembler will issue a warning message, and the substring will be 
set to null. 


8. If start_position+ span>length +1, then the substring will be that portion of the 
source_String starting at start_position to the end. The assembler will issue a warning 
message. 


Unfortunately, there is no substring notation meaning “from here to the end of the string”, 
which some other languages support. 


String expressions are constructed using the operations of substitution, concatenation, and 
substringing. One may also use type attribute references as character terms, but they are 
limited to “single-term” expressions with no duplication factors. 


Be aware that substitution of arithmetic-valued variable symbols into character (SETC) 
expressions will not preserve the sign of the arithmetic value! For example: 


8A SETA —5 
&C SETC ‘8A' €&C has value '5' (not '-5'!) 


If signed arithmetic is important, use arithmetic expressions and variable symbols; if signed 
valued must be substituted into ordinary statements with the proper sign, then you must con- 
struct a character variable with the desired sign, as in the following example. (Uses of the 
AIF and ANOP statements, and the sequence symbol .GenCon will be discussed shortly.) 


&A SETA —5 
BadConl OC F'gA! Constant has value § 
&C SETC ‘8A! &C has value '5" (not ‘-5'!) 
BadCon2 OC F'ac! Constant has value 5 
AIF (8A GE 0).GenCon Check sign of &A 
&C SETC '-', '&C! Prefix minus sign if negative 
-GenCon  ANOP 
GoodConst DC F'ac! Correctly signed constant with value -5 


Character Expressions: String Lengths 


e Use a Count Attribute Reference (K') to determine string lengths 


K'&c Sets &A to number of characters in &C¢ 


*12345' &C has value '12345' 
K'&c 8N has value 5 


null string 
K'&c &N has value 6 


(3) ‘AB &C has value ‘ABABAB' 
K'&c &N has value 6 
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String Lengths 


The number of characters in a character variable symbol can be determined using a Count 
attribute reference (K'). For example: 


&C 
&N 


&C 
&N 


&C 
&N 


SETC '12345! &C has value '12345' 
SETA K'&C &N has value § 

SETC '! null string 

SETA K'&C &N has value 6 

SETC (3)'AB! &C has value ‘ABABAB' 
SETA K'&C &N has value 6 


The Count attribute reference is very useful in cases where strings must be scanned from 
right to left; thus, 


&X 


SETC '&C'(K'&C,1) Extract rightmost character of &C 


assigns the rightmost character in the value of &C to &X. 


Comments on Substitution, Evaluation, and Re-Scanning 


The assembler uses a method of identifying points of substitution that may be different from 
the methods used in some other languages. 


1. 


Points of substitution are identified only by the presence of variable symbols. Ordinary 
symbols (or other strings of text) are never substituted. 


Statements are scanned only once to identify points of substitution. This means that if a 
substituted value seems to cause another variable symbol to “appear” (possibly sug- 
gesting further points of substitution), these “secondary” substitutions will not be per- 
formed. 


To illustrate, you might ask what happens in this situation: will the substituted value of 
&B in the DC statement be substituted again? 


&C SETC '&&B! &C has value ‘&&B' 

&C SETC '8&C'(2,2) &C has value ‘'&B' 

&B SETC ='XXX! &B has value 'XXxX' 

Con DC C'ac! Is the result '&B' or 'XXX'? 


The answer is “no”. In fact, this DC statement results in an error message: 
ASMA127S *** ERROR *** ILLEGAL USE OF AMPERSAND 


Because the assembler does not re-scan the DC statement to attempt further substi- 
tutions for &C, there will be a single ampersand remaining in the nominal value ('&B') of 
the C-type constant. 


As a further example, note that substitution uses a left-to-right scan, and that new vari- 
able symbols are not created “automatically”. For example, if the two character vari- 
able symbols &C1 and &C2 have values 'X' and 'Y' respectively, then the substituted 
value of '&C1&C2' is 'XY', and not the value of '&C1Y'. Similarly, the string '&&¢1.C2' 
represents '&&C1.C2', and not the value of '&XC2!'! 


The only mechanism for “manufacturing” variable symbols is that of the created vari- 
able symbol, whose recognition requires the specific syntax previously described. — 


This single-scan rule applies both to ordinary-statement substitutions, and to 
conditional-assembly statements. Thus, statements once scanned for points of substi- 
tution will not be re-scanned (or “re-interpreted”) further. 
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Consider the arithmetic expression '5*&A'. We would expect it to be evaluated by sub- 
stituting the value of &A, and then multiplying that value by 5. 


if this is used in statements such as 6S 


&A SETC "10! 
&B SETA 5* 8A 


then we would find that &B has the expected value, 50. However, in the following state- 
ments: 


&A SETC 13+4!' 
&B SETA 5*8A 


we are faced with several possibilities. First, is the value of & now 35 (corresponding to 
"5*(3+4)")? That is, is the sum 3+4 evaluated before the multiplication? Second, is the 
value of &B now 19 (corresponding to "(5*3)+4")? That is, is the string "5*3+4" evaluated 
according to the rules for arithmetic expressions? 


In fact, a third situation occurs: because the expression '5*&A' is not re-scanned in any 
way, the value of &A must be a self-defining term. Because it is not, the assembler 
produces this error message: 


ASMA102E *** ERROR *** Arithmetic term is not self-defining term; default = 0 


indicating that the substituted “term” 3+4 is improperly formed. 


A similar result occurs if predefined absolute symbols are used as terms. If they are 
used directly (without substitution), they are valid; however, the name of the symbol may 
not be substituted as a character string. To illustrate: 


N Equ 3+4 N has value 7 

&B SetA 5*N &B has value 35 © 
&N SetC 'N! Set &N to the character 'N' 

&C 8 =6SetA 5*&N Error message for invalid term! 
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Statement Selection 15 


Allows the Assembler to select different sequences of statements for 
further processing 


Key elements are: 
- Sequence symbols 
— Used to “mark” positions in the statement stream 
Two statements that refer to sequence symbols: 
- AGO conditional-assembly “unconditional branch” 
AIF conditional-assembly “conditional branch” 
One statement that helps “define” a sequence symbol: 


ANOP conditional-assembly “No-Operation” 
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Statement Selection 


The full power of the conditional assembly language lies in its ability to direct the Assembler 
to select different sequences of statements for processing. This allows you to tailor your 
program in many different ways, as we will see. 


The key facilities required for statement selection are sequence symbols, which are used to 
mark positions in the statement stream for reference by other statements, and the AIF and 
AGO statements, which allow the normal sequence of statement processing to be altered, 
based on conditions specified by the programmer. The ANOP statement is provided as a 
“place holder” for a sequence symbol. 
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Sequence Symbols and the ANOP Statement 


e Sequence symbols 
- Written as an ordinary symbol preceded by a period (.) 


A -Repeat_Scan -Loop_Head .Error12 


Used to mark a statement 

— Defined by appearing in the name field of a statement 

Not assigned any value (absolute, relocatable, or other) 

Purely local scope; no sharing of sequence symbols across scopes 
Cannot be created or substituted (unlike ordinary and variable symbols) 
— Cannot even be created in a macro-generated macro (!) 

~ Never passed as values of any symbolic parameter 


Used as target of AIF, AGO statements to alter sequential statement 
processing 
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Sequence Symbols and the ANOP Statement ... 


ANOP = conditional-assembly “No-Operation” 


- Serves only to hold a sequence-symbol marker before statements that 
wouldn’t have room for it in the name field 


-Target ANOP . 
&ARV SETA &ARV+1 Name field required for target variable 


No other effect 


Conceptually similar to (but very different from!) 


Target EQU * For ordinary symbols in ordinary assembly 


July 1893 High Level Assembier Tutorial Guide 
C Copyright 18M Corporation 1883 


Sequence Symbols and the ANOP Statement 


Sequence symbols are the key to statement selection: they “mark” the position of a specific 
statement in the stream of statements to be processed by the assembler. They are written 
as an ordinary symbol preceded by a period (.), as in the following examples: 


A .Repeat_Scan . Loop_Head .Errori2 


Sequence symbols have some unusual properties compared to ordinary symbols. 


e Sequence symbols are defined by appearing in name field of any statement. They may 
appear on ordinary-assembly statements and on conditional-assembly statements, with 
no difference in meaning or behavior. 
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e Sequence symbols are not assigned an absolute or relocatable value, and they do not 
appear in the assembler’s Symbol Table. They cannot be used in expressions of any 
kind. 7 


e Sequence symbols have purely local scope. That is, there is no sharing of sequence 
symbols between macros, or between macros and ordinary “open code” assembly. 


e Sequence symbols cannot be created or substituted (unlike ordinary and variable 
symbols). 


e Sequence symbols are never passed as values of any symbolic parameter. Thus, 
although they can appear in the name field of a macro instruction statement (or macro 
“call”), they are never made available to the macro definition as the value of a name- 
field variable symbol. 


e Sequence symbols are used as the target of AIF and AGO statements to alter sequential 
statement processing, and for no other purpose. 


The ANOP statement is provided as a “place holder” for a sequence symbol that could not 
otherwise be attached to a desired statement. This is illustrated in the following example, 
where the desired “target” is a SETA statement, which requires that an arithmetic variable 
symbol appear in the name field: 


~Target ANOP 
&ARV SETA &ARV+1 Name field required for target variable 


Thus, the ANOP statement provides a way for other AIF and AGO statements to refer to the 
SETA statement. 
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The AGO Statement 


¢ Unconditionally alters normal sequential statement processing 
- Assembler breaks normal sequential statement processing 


- Resumes processing at statement marked with the specified sequence 
symbol 


- Two forms: Ordinary AGO and Extended AGO 
Ordinary AGO (Go-To statement) 
AGO sequence_symbol 
Example: 
AGO .Target Next statement processed marked by .Target 
Example of use: 


AGO. 
* (1) This statement is ignored 
BB ANOP 


* (2) This statement is processed 
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The AGO Statement 


The function of the AGO statement is to unconditionally alter the sequence of statement 
processing, which resumes at the statement “marked” with the specified sequence symbol. 
It is written in the form 


AGO sequence_symbol 


Example: 
AGO .Target Next statement processed marked by .Target 


The Assembler breaks its normal sequential statement processing, and resumes processing 
at the statement “marked” with the specified sequence symbol. For example, 


AGO .BB 
* (1) This statement is ignored 
-BB = ANOP 


* (2) This statement is processed 


the AGO statement will cause the following comment statement (1) to be skipped, and proc- 
essing will resume at the ANOP statement. 
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The Extended AGO Statement 


e Extended AGO (Computed Go-To, Switch statement) 


AGO = (ar ith_expr)seqsym_1[,seqsym_k]... 


Example: 


boa 2) } 
AGO (28u) .SW2, .SW2, .SW3, .S1 Default fol then 
MNOTE 12,'Invalid value of &&SW = &SW..' gd as f {A tbeu 


Value of arithmetic expression determines which “branch” is taken 
from sequence-symbol list 


m - Value must lie between 1 and number of sequence symbols in “branch” 
list 


Warning! if value of arithmetic expression is invalid, no “branch” is 
taken! 
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The Extended AGO Statement 


The assembler provides a convenient extension to the simple imperative (unconditional) 
AGO statement, in the form of the “Computed AGO” statement, analogous to a “switch” or 
“case” statement in other languages. The operand field contains a parenthesized arithmetic 
expression, followed by a list of sequence symbols, as shown in the following example. 


AGO (arith_expr)seqsym_1[,seqsym k]... 


Figure 2. General Form of the Extended AGO Statement 


The operation of this extended AGO statement is simple: the value of the 
arithmetic_expression is used to select one of the sequence symbols as a “branch target”: if 
the value is 1, the first sequence symbol is selected; if the value is 2, the second sequence 
symbol is selected; and so forth. However, because it is possible that the value of the arith- 
metic expression does not correspond to any entry in the list (e.g., the value of the 
expression may be less than or equal to zero, or larger than the number of sequence 
symbols in the list), the assembler will not take any branch, and will not issue any diagnostic 
message about the “failed” branch! Thus, it is important to verify that the values of arithmetic 
expressions used in extended AGO statements are always valid. 


The operation of the extended AGO statement illustrated in Figure 2 is precisely equivalent 
io ihe following set of AIF statements (which wiil be described shortly): 


. AIF (arith expr EQ 1)seqsym_1 
AIF (arith expr EQ 2)seqsym 2 


: AIF (arith_expr EQ k)seqsym_k 


This construction helps to illustrate how and when it is possible for no “branch” to be taken. 
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The AIF Statement 


Conditionally alters normal sequential statement processing 


Two forms: Ordinary AIF and Extended AIF 
Ordinary AIF: 


AIF (boolean expression) seqsym 
AIF (8A GT 10).Exit_Loop 


If boolean_expression is 
true, “branches” to specified sequence symbol 
false, processing continues with next sequential statement 


AIF (&2 GT 46).80 
* (1) This statement {s processed if (NOT (&2Z GT 46)) 
BD ANOP 


* (2) This statement is processed 
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The AIF Statement 
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The AIF statement provides a method for conditionally selecting a sequence of statements, 
by testing a condition before deciding to “branch” or not to the statement designated by a 
specified sequence symbol. The ordinary AIF statement is written in this form: 


AIF (boolean _expression)seqsym 


Example: 
AIF (8A GT 10).Exit_Loop 


Ifthe “boolean_expression” is true, statement processing will continue at the statement 
marked with the specified sequence symbol. If the “boolean_expression” is false, processing 
continues with the next sequential statement following the AIF. For example: 


AIF (&A GT 10).BD 
* (1) This statement is processed if (NOT (8A GT 16)) 
.BD — ANOP 
* (2) This statement is processed 


In this case, the statement following the AIF will be processed if the boolean expression 


(&A GT 10) is false; if the condition defined by the boolean condition is true, the next state- 
ment to be processed will be the ANOP statement. 
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The Extended AIF Statement 


e Extended AIF (Multi-condition branch, Case statement) 


AIF (bool _expr_1)seqsym_1[, (bool_expr_n)seqsym nj... 


e Boolean expressions are evaluated in turn until first true one is found 


- Remaining boolean expressions are not evaluated 
e Example: 


AIF (&A GT 10) .$S1, (&BO00L2).$S2,('&C' EQ '*').SS3 


July 1993 High Level Assembler Tutorial Guide 
€ Copyright IBM Corporation 1993 


The Extended AIF Statement 


The extended, or multi-condition, form of the AIF statement allows you to write multiple con- 
ditions and “branch” targets on a single statement, as shown in the following: 


© AIF (bool_expr_1)seqsym_1[, (bool_expr_n)seqsym_n]... 
Figure 3. General Form of the Extended AIF Statement 
The boolean expressions are evaluated in turn until the first true expression is found; the 
next statement processed will be the one “marked” by the corresponding sequence symbol. 


The remaining boolean expressions are not evaluated after the first true expression is found. 


An example of an extended AIF statement is: 
AIF (8A GT 10).SS1, (&B00L2).SS2,('&C' EQ '*').SS3 


The extended AIF statement illustrated in Figure 3 is entirely equivalent to the following 
sequence of ordinary AIF statements: 


AIF (bool _expr_1)seqsym 1 
AIF (bool _expr_2)seqsym 2 


. AIF (bool_expr_n)seqsym_n 


The primary advantage of the extended AIF statement is in providing a concise notation for 
what would otherwise require multiple AIF statements. 
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Examples of Conditional Assembly 


We will now describe some simple examples of open-code conditional assembly. Further 
examples of conditional assembly techniques will be illustrated later, when we discuss 
macros. 


Example: Generate a Byte String with Values 1-N 


e Sample 0: write everything by hand 


Wi Equ 5 Predefined absolute symbol 
oc AL1(1,2,3,4,N) Define the constants 


- Defect: if the value of N changes, must rewrite the DC statement 
Sample 1: generate separate statements 


‘ aL tof 
equ 5 o‘” Predefined absolute symbol 
LCLA &J Local arithmetic variable symbol 
AIF (&J GE N).Done Test for completion (N could be LE 6!) 
SETA &J+1 Increment &J 
oc AL1(&J) Generate a byte 
AGO .Test Go to check for completion 
-Done ANOP Generation completed 
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Example: Generate a Byte String with Values 1-N ... 


e Sample 2: generate a single string 


Equ 5 Predefined absolute symbol 
LCLA &K Local arithmetic variable symbol 
LCLC &S Local character variable symbol 
SETA 1 Initialize counter 
AIF (&K GT N).Done2 Test for completion (N could be LE 6!) 
SETC ‘1° Initialize string 

ANOP Loop head 

SETA &K+1 Increment &K 

AIF (&K GT N).Donel Test for completion 

SETC ‘&S'.',&K' Continue string 

AGO =. Loop Branch back to check for completed 
.Donel OC =AL1(&S.) Generate the byte string 
.Done2 ANOP — Generation completed 


Try it with "N EQU 30" ... What happens to the DC statement? 


Try it with "N EQU 90" ...What happens? Sring press crrov bse 
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Generate a Sequence of Byte Values 


Suppose we wish to generate DC statements defining a sequence of byte values from 1 to N, 
where N is a predefined value. This could naturally be done by writing statements like 


N EQU 12 
BC. -:AL1(152; 35 e058) 
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but this requires knowing the exact value of N every time the program is modified and re- 
assembled. 


Conditional assembly techniques can be used to solve this problem so that changing the 
EQU statement defining N will not require any rewriting. We can generate the sequence of 
DC statements as follows: 


N Predefined absolute symbol 
&J Local arithmetic variable symbol 
Test (&J GE N).Done Test for completion (N could be LE 0!) 


&J &J+1 Increment &J 
AL1(&J) Generate a byte 
Go to check for completion 
-Done ANOP Generation completed 


Figure 4. Generating a Sequence of Bytes, Individually Defined 


The operation of this loop is simple. The LCLA declaration of &J also initializes it to zero (we 
could not have omitted the declaration in this example, because the first appearance of &J is 
not in a SETA statement). The AIF statement compares &J to N (a predefined absolute 
symbol), and if it exceeds N, a “branch” is taken to the label .Done. (In fact, the Assembler 
implements the “branch” by searching the source file for an occurrence of the sequence 
symbol in the local context of “open code”.) If the AIF test does not change the flow of state- 
ment processing, the next statement increments &J by one, and its new value is then substi- 
tuted in the DC statement. The following AGO then returns control to the test in the AIF 
statement. 


Alternatively, we could generate only a single DC statement by using a technique that con- 
structs the nominal value string for the DC statement, like the following: 


N EQU 5 Predefined absolute symbol 
LCLA &K Local arithmetic variable symbol 
LCLC &$ Local character variable symbol 
&K SETA 1 Initialize counter 
AIF (&K GT N).Done2 Test for completion (N could be LE 0!) 
&S SETC ‘1! Initialize string 
.Loop ANOP Loop head 
&K SETA &K+1 Increment &K 
AIF (&K GT N).Donel Test for completion 
&S SETC '&S'.',&K! Continue string 
AGO .Loop Branch back to check for completed 
-Donel DC AL1(&S.) Generate the byte string 
~Done2 ANOP Generation completed 


Figure 5. Generating a Sequence of Bytes, as a Single Operand String 


In this program fragment, a single character string is constructed with the desired sequence 
of values separated by commas. The first SETC statement sets the local character variable 
symbol &C to '1', and the following loop then concatenates successive values of the arith- 
metic variable symbol &K onto the string with a separating comma, on the right. When the 
loop is completed, the DC statement inserts the entire string of numbers into the nominal 
values field of the AL1 operand. 


It is instructive to test this example with values of N large enough to cause the string &S to 
become longer than (say) 60 characters; try assigning a value of 30 to N, and observe what 
the assembler does with the generated DC statement. (Answer: it creates a continuation 
automatically!) 
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Both these examples share a shortcoming: if more than one such sequence of byte values is 
needed in a program, with different numbers of elements in each sequence, these “blocks” 
of conditional assembly statements must be repeated. We will see in “Generating a Byte 
Sequence” on page 77 that a simple macro definition can make this task easier to solve. 


Example: System-Dependent I/O Statements 


e Suppose a module declares I/O blocks for MVS, CMS, and VSE: 


&0pSys SETC ‘MVS’ Set desired operating system 


AIF (‘&OpSys' NE ‘MVS').T1 Skip if not MVS 

Input OCB DDNAME=SYSIN,...etc... Generate MVS DCB 
AGO =«€T4 

io 0k AIF (‘&OpSys' NE ‘CMS').T2 Skip if not CMS 

Input FSCB ,LRECL=86,...etc... Generate CHS FSCB 
AGO «.T4 

72 AIF (‘&OpSys' NE 'VSE').73 Skip if not VSE 

Input DTFCD LRECL=860,...etc... Generate VSE DTF 
AGO .T4 

13 MNOTE 8, ‘Unknown &&0pSys value ''&OpSys''.' 

.74 ANOP 


¢ Setting of &OpSys selects statements for running on one system 
- Assemble the module with a system-specific macro library 
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Generating System-Dependent I/O Statements 
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Suppose you are writing a module that provides operating system services to a larger appli- 
cation. As a simple example, suppose one portion of the module must read input records, 
and that you wish to use the appropriate system-interface macros for each of the 
System/360/370/390’s MVS, CMS, and VSE operating systems. 


This is very simply solved using conditional-assembly statements to select the sequences 
appropriate to the system for which the module is intended. Suppose you have defined a 
character-valued variable symbol &0pSys whose values may be MVS, CMS, or VSE. Then the 
needed code sequences might be defined as in Figure 6 on page 29: 
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SETC 'MVS! Set desired operating system 


© AIF ('&OpSys' NE 'MVS').T1 Skip if not MVS 
DCB DDNAME=SYSIN,...etc... Generate MVS DCB 
AGO .T4 
AIF ('&OpSys' NE 'CMS').T2 Skip if not CMS 
FSCB ,LRECL=80,...etc... Generate CMS FSCB 
AGO .T4 
‘ AIF ('&OpSys' NE 'VSE').T3 Skip if not VSE 
- DTFCD LRECL=80,...etc... Generate VSE DTF 


AGO .T4 
MNOTE 8,'Unknown &&OpSys value ''&OpSys''.! 
ANOP 


Figure 6. Generating a Sequence of Bytes, as a Single Operand String 


In this example, different blocks of code contain the necessary statements for particular 
operating environments. In any portion of the program that contains statements particular to 
one of the environments, conditional assembly statements allow the assembler to select the 
correct statements. By setting a single variable symbol &0pSys to an appropriate value, you 
can tailor the application to a chosen environment without having to make into multiple 
copies of its processing logic, one for each environment. 


Thus, for example, the first AIF statement tests whether the variable symbol &0pSys has 
value 'MVS'; if so, then the following statements generate an MVS Data Control Block. 
(Naturally, you will need to supply an appropriate macro library to the assembler at 
assembly time!) 


The technique illustrated here allows you to make your programs more portable across 
operating environments, without requiring major rewriting efforts or duplicated coding each 
time some new function is to be added. 
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© Macros 


Macros are a powerful mechanism for enhancing any language, and they are a very impor- 
tant part of the System/360/370/390 Assembler Language. Macros are widely used in many 
ways to simplify programming tasks. 


We will begin our discussion with a conceptual overview of the basic concepts of macros, in 

: a way that is not specific to the Assembler Language.' This will be followed by an investi- 
gation of the System/360/370/390 Assembler Language’s implementation of macros, 
including the following topics: 


macro definition: how to define a macro 


macro encoding: how the assembler converts the definition into an internal format to 
simplify interpretation and expansion 


macro-instruction recognition: how the assembler identifies a macro call and its ele- 
ments 


macro parameters and arguments 

macro expansion 

macro argument attributes and structures 
global variable symbols 


examples of macros. 


What is a Macro Facility? 


¢ A mechanism for extending a language 
- Introduces new statements into the language 
- Defines how the new statements translate into the “base language” 


- Allows mixing old and new statements 


In Assembler Language, “new” statements are called 
macro instructions or macro calls 


Easy to create application-specific languages 
Typical use is to extend base language 
— Can even hide it entirely! 
Create higher-level language appropriate to application needs 


Can be made highly portable, efficient. 
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1 Some of the material in this chapter is based on an excellent overview article by William Kent, titled 
“Assembler-Language Macroprogramming: A Tutorial Oriented Toward the IBM 360” in the ACM Com- 


puting Surveys, Vol. 1, No. 4 (December 1969), pages 183-196. 
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What is a Macro Facility? 


Most simply, a macro facility is a mechanism for extending a language. It can be used not 
only to introduce new statements into the language, but also to define how the new state- 
ments should be translated into the “base language” on which they are built. One major 


advantage of macros is that they allow you to mix “old” (existing) and “new” statements, so 
that your language can grow incrementally to accommodate new functions, added require- 


ments, and other benefits as and when you are able to take advantage of them. 


In the Assembler Language, these new statements are called “macro instructions” or 


“macro calls”. The use of the term “call” implies a useful analogy to subroutines; there are 


many parallels between (assembly-time) macro calls and (run-time) subroutine calls. 


Macros and macro techniques make it very easy to create application-specific languages: 


e you can create higher-level languages appropriate to the needs of particular application 


areas 


e the language can be made highly portable and efficient 


e typical uses are to extend the base language on which the extended language is built 
(in fact, it is possible to hide the base language entirely’). 


Benefits of Macro Facilities 26 


Re-use: write once, use many times and places (even within a single 
application) 


Reliability: write and debug “localized logic” once only 
Reduced coding effort: minimize focus on uninteresting details 


Increased flexibility and adaptability of programs 


- Greater application portability 

Simplification: hide complexities, isolate impact of changes 
Easier application debugging: fewer bugs and better quality 
Standardize coding conventions painlessly 


Encapsulated, insulated interfaces to other functions 
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Benefits of Macro Facilities 
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Macro facilities can provide you with many direct and immediate benefits: 


e Code re-use: once a macro is written, it becomes available to as many programmers 
and applications as are appropriate. A single definition can find multiple uses (even 
within a single application). 


e Reliability: code and debug the logic in one place. 


e Reduced coding effort: the coding in a macro needs to be written only once, and then 
can be used in many places. 
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ments of your programming language, relieving you of the need to be concerned with 
details that are typically only marginally relevant to your programming task. 


e Increased flexibility and adaptability of programs: you can adapt your applications to 
different requirements by modifying only the macro definitions, without having to revise 
the fundamental logic of the program. 


¢ Greater application portability: because almost every system supports a macro assem- 
bler, it is easy to port an application written in “macro language” to another host envi- 
ronment simply by writing an appropriate set of macros definitions on the new system.? 


e Easier debugging, with fewer bugs and better quality: once you have debugged your 
macros, you can write your applications using their higher-level concepts and facilities, 
and then debug your programs at that higher level. Concerns with low-level details are 
minimized, because you are much less likely to make simple oversights among masses 
of uninteresting details. 


e Standardize coding conventions painlessly: if your organization requires that certain 
coding conventions be followed, it is very simple to embody them in a set of macros that 
all programmers can use. Then, if the conventions need to change, only one set of 
objects — the macros — needs to be changed, not the entire application suite. 


e Provide encapsulated interfaces to other functions, insulated from interface changes: 
using macros, you can support interfaces among different elements of your applications, 
and between applications and operating environments, in a controlled and defined way. 
This means that changes to those interfaces can be made in the macros, without 
affecting the coding of the applications themselves. 


e Localized logic: specific and detailed (and often complex) code sequences can be imple- 
mented once in a macro, and used wherever needed, without the need for every user of 
the macro to understand the “inner workings” of the macro’s logic. 


The SNOBOL4 language was implemented entirely in terms of a set of macros that defined a “string 
processing implementation language”. The entire SNOBOL4 system could be “ported” to a new system 
with what the authors called “about a week of concentrated work by an experienced programmer”. 
You may be interested in consulting The Macro Implementation of SNOBOL4, by Ralph Griswold. 


Macros 33 


Ine macro Concept -- Fundamental mecnanisms Zi 


° Macro processors rely on two basic mechanisms: 
1. Macro recognition: identify some character string as a macro “call” 


2. Macro expansion: generate a character stream to replace the “call” 


Macro processors typically do three things: 


Text insertion: injection of one stream of source program text into another 
stream 


Text modification: tailoring (“parameterization”) of the inserted text 


Text selection: choosing alternative text streams for insertion 
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The Basic Macro Concept 


Macro processors typically rely on two basic processes: 


e Macro recognition requires that the processor identify some string of characters as a 
macro invocation or macro call, indicating that the string is to be replaced. 


e Macro expansion or macro generation causes the macro definition to be interpreted by 
the processor, with the usual result that the original string is replaced with a new (and 
presumably different) string. 


In macro expansion, there are three fundamental mechanisms used by almost all macro 
processors: 


e text insertion: the creation of a stream of characters to replace the string recognized in 
the macro “call” 


e text parameterization: the tailoring and adaptation of the generated stream to the condi- 
tions of the particular call 


e text selection: the ability to generate alternative streams of characters, depending on 
various conditions available during macro expansion. 


These correspond to the mechanisms already described for the conditional assembly lan- 
guage: for example, text parameterization uses the process of substitution, and text 
selection uses that of statement selection. 
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‘Basic Macro Concepts: Text Insertion 


¢ ‘Text insertion: injection of one stream of source program text into 
another stream 


Macro Definition 
Name = MAC61 


cc 
DD 


Main Program Logical Effect 


AA 
BB 
cc 
DD 
EE 
FF 


¢ The processor recognizes MACO1 as a macro name 


* The text of the macro definition replaces the “macro call” in the Main 
Program 
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Text Insertion 


The simplest and most basic mechanism of macro processing is that of replacing a string of 
characters, or one or more statements, by other (often longer and more complex) strings or 
sets of statements. 


In Figure 7, a set of statements has been defined to be a macro with the name MACO1. When 
- the processor of the Main Program recognizes the string MACO1 as matching that of the macro, 
@ that string is replaced by the text within the macro definition. 


This is called text insertion: the injection of one stream of source text into another stream. 


Macro Definition Main Program Logical Effect 
Name = MACO1 


CC 
| §=DD 


Figure 7. Basic Macro Mechanisms: Text Insertion 
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Basic Macro Concepts: Text Parameterization 29 


¢ Text modification: tailoring of the inserted text (“parameterization”) 
Macro Definition Main Program Logical Effect 


Name = MACO62 
Parameters X,Y 


¥ 
MAC@2 CC,0D | —> 


Processor recognizes MACO2 as a macro name, with arguments CC,DD 
- Arguments CC,0D are associated with parameters X,Y by position 
The text of the macro definition is modified during insertion 
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Text Parameterization and Argument Association 


Simple text insertion has rather limited uses, because we usually want to tailor and adapt 

the inserted text to accommodate the various conditions and situations of each macro invo- 

cation. The simplest form of such adaptation is “text parameterization”. In Figure 8, the 

macro with name MACQ2 is defined with two parameters X and Y: that is, they are merely 

place-holders in the definition that indicate where other text strings are expected to be 

inserted when the macro is expanded. © 


Macro Definition Main Program Logical Effect 
Name = MACO2 
Parameters X,Y 


BB AA 
X MACO2 CC,DD 


Y FF 
EE 


Figure 8. Basic Macro Mechanisms: Text Parameterization 


This example illustrates text modification: tailoring of the inserted text (“parameterization”) 
depending on locally-specified conditions. - 


When a macro call is recognized, it is normal for additional information (besides the simple 

act of activating the definition) to be passed to the macro expansion. Thus, when the . 
processor of the Main Program recognizes MACQ2 as a macro name, it also provides the two 

arguments CC and DD to the macro expander, which substitutes them for occurrences of the 

two parameters X and Y, respectively. 


The argument CC is associated with parameter X, and DD is associated with Y. This simple 
example of parameter-argument association is typical of many macro processors: associ- @ 
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ation proceeds in left-to-right order, matching each positional parameter in turn with its cor- 
responding positional argument. Other forms of association are possible. 
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Basic Macro Concepts: Text Selection & 


e Text selection: choosing alternative text streams for insertion 


Macro Definition Main Program Logical Effect 
Name = MAC63 
Parameter X 


JJ : 
if (X = 6) skip 1 stmt 
KK 
LL 


¢ Processor recognizes MAC03 as a macro name with argument 0 or 1 
¢ - Conditional actions in the macro definition allow selection of different 
insertion streams 
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Text Selection 


Text selection is fundamental to most macro processors, because it allows choices among 

alternative sequences of generated text. In Figure 9, a simple form of text selection is 

modeled by the if statement: a simple test of the argument corresponding to the parameter 

X tells whether or not to generate the string KK. If the argument is 0, KK is not generated; — 

otherwise it is. @ 


Macro Definition Main Program Logical Effect 
Name = MACO3 
Parameter X 


JJ 
if (X = 0) skip 1 stmt 


KK 
LL 


Figure 9. Basic Macro Mechanisms: Text Selection 
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Basic Macro Concepts: Nesting 31 


¢ Generated text may include calls on other (“inner”) macros 


- New statements can be defined in terms of previously-defined extensions 


Inner macro calls recognized during expansion of the outer macro 


- Not during definition and encoding of the outer macro 


Can pass arguments of outer macros to inner macros that depend on arguments 
to, and analyses in, outer macros 


Provides better independence and encapsulation 
Allows passing parameters through multiple levels 


Can change definition of inner macros without having to re-define the outer 


Generation of statements by the outer (enclosing) macro is 
interrupted to generate statements from the inner 


Multiple levels of call nesting OK (including recursion) 
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Macro Nesting 


_A key strength of the macro language is its ability to build new capabilities on existing facili- 
ties. The most common of these abilities is called “macro nesting”: generated text may 
include (or create!) calls on other macros (“inner macro calls”). It is by this mechanism that 
new statements can be defined in terms of previously-defined extensions; it is fundamental 

- to much of the power and “leverage” of macro languages. 


The inner calls are recognized during expansion of the outer (enclosing) macro, not during 
macro definition and encoding. This may seem a very minor and obscure technical detail, 
but it turns out in practice to have wide-ranging implications. 


By deferring the recognition of inner macro calls until the enclosing macro is expanded, 
you can pass arguments to inner macros that depend on arguments to, and analyses in, 
outer macros. 


Recognition following expansion provides better independence and encapsulation: you 
can change the definition of the inner macro without having to re-define the outer. 


You will also save coding effort: if the definition of an inner macro needed to be 


- changed, and its definition was already “embodied” in some way in other macros that 


called it, then all the “outer” macro definitions would have to be revised. 


The generation process for inner macro calls requires that the macro processor maintain 
some kind of “push-down stack” for its activities. 


Generation of statements by the outer (enclosing) macro is suspended temporarily to 
generate statements from the inner. 


Multiple levels of call nesting are quite acceptable (including recursion: a macro may 
call itself directly or indirectly), and are often a source of added power and flexibility. 
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Macro Nesting: Example 


¢ - Two macro definitions: OUTER contains a call on INNER 


Macro Definitions Main Program Logical Effect 
Name = OUTER 


Name = INNER 
cc 
DD 


e Expansion of OUTER is suspended until expansion of INNER 
completes 
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In the example in Figure 10, two macros named OUTER and INNER are known to the 
processor of the Main Program. When the name OUTER is recognized as a macro name, 
processing of the Main Program is suspended and expansion of the OUTER macro begins. 
When INNER is recognized as as macro name, processing of the OUTER macro is also sus- 
pended and expansion of the INNER macro begins. When the INNER macro expansion com- 
pletes, the OUTER macro resumes expansion; when the expansion of the OUTER macro 
completes, processing resumes in the Main Program following the OUTER statement. 


Macro: Definitions Main Program Logical Effect 
Name = OUTER 


BB AA 
INNER OUTER 
EE FF 


Name = INNER 
CC 
DD 


Figure 10. Basic Macro Mechanisms: Nesting 


The power of a macro facility is enhanced by its ability to combine the basic functions of text 
insertion, text parameterization, text selection, and macro nesting. 


Each of the features, concepts, and capabilities described above can be expressed in a way 
natural to the System/360/370/390 Assembler Language. 
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The Assembler Language Macro Definition 


* Amacro definition has four parts: 


Macro Header (begins a definition). 


Model of the macro instruction 

* that can call on this definition; 
a model of the new statement 
introduced into the language by 
this definition. 


. Declarations, conditional assembly 
statements, and text for selection, 
modification, and insertion. 


Macro Trailer (ends a definition). 
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The Assembler Language Macro Definition ... 34 


Declares a macro name that represents a defined stream of program 
text 


Prototype statement declares parameter variable symbols 
© Model statements (“macro body”) provide logic and text 


- Format of prototype dictated by desire not to introduce arbitrary 
forms of statement recognition for new statements 


Definition may be found 
- “in-line” (a “source macro definition”) 
- ina library 


- or both 


Where the definition is found affects recognition rules 
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The Assembler Language Macro Definition 


2 The definition of a macro declares the macro name that is to stand for (represent) a given 
: stream of program text. The general form of an Assembler Language macro definition has 
four parts: 
" 1. amacro header statement (MACRO: the start of the definition) 


2. a prototype statement, which provides the macro name and a model of the macro- 
instruction “call” that must be recognized in order to activate this definition 


3. the macro body, containing declarations of variable symbols, model statements to be 
parameterized and generated, and conditional assembly statements to assign values to 
~ variable symbols and to select alternative processing sequences | 
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4. amacro trailer statement (MEND: the end of the definition). 


These four parts are illustrated in Figure 11: 


Macro Header (begins a definition). 


Model of the macro instruction 
that can call on this definition; 

a model of the new statement 
introduced into the language by 
this definition. 

Declarations, conditional assembly 
Statements, and text for selection, 
modification, and insertion. 


Macro Trailer (ends a definition). 


Figure 11. Assembler Language Macro Definition: Format 


While many possible forms of macro definition and recognition are possible, the general 
format used in the System/360/370/390 Assembler Language is dictated by a desire not to 
introduce arbitrary forms of statement syntax and recognition rules for new statements. This 
has the advantage that there is no need to distinguish language extensions from the base 
language. 


A macro definition may be “in-line” (also called a “source macro definition”) or in a library. 
Where the definition is found by the assembler affects the recognition rules, as will be 
described in “Macro-instruction Recognition” on page 45. 


Macro-Instruction Definition Example 


42 


We can rewrite the example in Figure 7 on page 35 to look like a “real” macro, as follows: 


Macro Definition Main Program Logical Effect 


Figure 12. Assembler Language Macro Mechanisms: Text Insertion by a “Real” Macro 


The “+” characters shown in the “Logical Effect” column correspond to the characters 
inserted by the assembler in its listing to indicate that the corresponding statements were 
generated from a macro. 
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Macro Comments and Readability Aids 


¢ Assembler Language supports two types of comment statement: 


1. Ordinary comments (“*” in first column position) 


— Can be generated from macros like all other model statements 


2. Macro comments (“.*” in first two column positions) 


- Not model statements; never generated 


MACRO 
&N SAMPLE] &A 

-* This is macro SAMPLE]. It has a name-field parameter 8N, 
-* and an operand-field positional parameter &A. 

ba This comment is a model statement, and may be generated 


° Two “formatting” instructions are provided for macro listings: 


1. ASPACE provides blank lines in listing of macros 
2. AEJECT-causes start of a new listing page for macros 
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Macro Comments and Readability 


The macro facility provides a way to embed “macro comments” into the body of a macro 
definition. Because both ordinary comment statements (with an asterisk in the left margin) 
and blank lines (for spacing) are model statements, they may be part of the generated text 
‘from a macro expansion. Macro comments are never generated, and use the characters .* 
in-the left margin, as illustrated below: 


MACRO 

SAMPLE] &A 
This is macro SAMPLE1. It has a name-field parameter &N, 
and an operand-field positional parameter &A. 


This comment is a model statement, and may be generated 


MEND 


-Figure 13. Example of Ordinary and Macro Comment Statements 


It is good practice to comment macro definitions generously, because the conditional 
assembly language is sometimes difficult to read and understand. 


The formatting and printing of macro definitions can be simplified by using the ASPACE and 
AEJECT statements. ASPACE provides blank lines in the assembler’s listing of a macro defi- 
nition, and AEJECT causes the assembler to start a new listing page when it is printing a 
macro definition. Both are not model statements, and are therefore never generated. 
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Macro-Definition Encoding 


° Assembler converts a macro definition into an internal format 
Macro name is identified and saved 
All parameters are identified 


Model and conditional assembly statements converted to “internal text” 
for faster interpretation 


All points of substitution are marked 


Some errors in model statements are diagnosed 


— Others may not be detected until macro expansion is completed 


“Dictionary” space (variable-symbol tables) are defined 


Avoids the need for repeated searches and scans on subsequent 
uses 
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Macro-Definition Encoding 


Because the System/360/370/390 Assemblers have been designed to support extensive use 
of macros, their implementation reflects a need to provide efficient processing. Thus, the 
assembler initially converts macro definitions into an encoded internal format for later use; 
this is sometimes called “macro editing”. 


e The macro’s name is identified and saved (so that later references to the macro name 
can be recognized as macro calls). 


e All parameters are identified, and entries are made in a “local macro dictionary” for 
them. 


e Model and conditional assembly statements are converted to “internal text” for faster 
interpretation. 


¢ All points of substitution are identified and marked. Because these are determined 
during macro encoding, it is perhaps more understandable why substituting strings like 
'SA' will not cause a further effort to re-scan the statement and substitute a new value 
represented by '8&A'. 


e Some errors in model statements are diagnosed, but others may not be detected until 
macro expansion is attempted. 


e “Dictionary” space (variable-symbol tables) are defined for local variable symbols, and 
space is added to the global variable symbol dictionary for newly-encountered global 
names. 


Encoding a macro definition in advance of any expansions avoids the need for repeated 
library searches and encoding scans on subsequent uses of the macro. 
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Macro-Iinstruction Recognition 


¢ Name recognition activates interpretation of the macro definition 


- Also cailed “macro expansion” or “macro generation” 
A macro “call” could use a special CALL syntax, such as 
MCALL macroname(argl,arg2,etc...) 


MCALL macroname,argl,arg2,etc... 


Advantages to having syntax match base language’s: 
~ No special characters, statements, or rules to “trigger” recognition 
7 . No need to distinguish language extensions from the base language 


- Allows overriding of most existing opcodes 


No need for “MCALL”; just make “macroname” the operation code 


July 1983 High Level Assembler Tutorial Guide 
© Copyright IBM Corporation 1893 


Macro-Instruction Recognition 


When the assembler scans a statement, and identifies its operation code as a macro name, 
recognition of the name triggers an activation of an interpreter of the encoded form of the 
macro definition. This is called “macro expansion” or “macro generation”, and typically 
results in insertion of program text into the assembler’s input stream. 


' Both macro name declaration (definition) and recognition have specific rules that are closely 
®@ | tied to the base language syntax of the System/360/370/390 Assembler Language. A macro 
“call” could use or require a special CALL syntax, such as 


MCALL macroname(argl,arg2,etc...) 
or MCALL macroname,argl,arg2,etc... 


However, there are advantages to having the syntax of macro calls match the base lan- 
guage’s, and to allow overriding of existing opcodes; hence, we simply elide the MCALL and 
make the “macroname” become the operation code and the arguments become the operands 
of the macro instruction statement. 
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Macro-Instruction Recognition Rules 


1. If the operation code is already known as a macro name, use its 
definition 


If an operation code does not match any operation code already 
known to the assembler (i.e., it is “possibly undefined”): 


Search the library for a macro definition of that name 
If found, encode and then use that macro definition 


If there is no library member with that name, the operation code is flagged 
as “undefined”. 


Macros may be redefined during the assembly! 


e New macro definitions supersede previous operation code definitions 
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Macro-Instruction Recognition Rules 


The assembler recognizes a macro instruction as follows: 


1. Ifthe macro name has already been defined in the program (as a “source” or “in-line” 
definition, either explicitly or because a COPY statement brought it in-line from a library, 
or because a previous macro instruction statement brought the definition from the 
library), use it in preference to any other definition of that operation. 


e You may use a macro definition to override the assembler’s default definitions of all 
machine instruction statements, and of most “native” Assembler Instruction state- 
ments (generally, the conditional-assembly statements cannot be overridden). 


2. If an operation code does not match any operation code “known” to the assembler (i.e., 
itis “possibly undefined”), the assembler will then: 


a. Search the library for a macro definition of that name. 


b. Ifthe assembler finds a library member with that name, the macro name defined on 
the prototype statement must match the member name. The assembler will then 
encode and use this definition. 


c. If there is no library member with that name, then the operation code is flagged as 
“undefined”. 


While it is not a common practice to do so, macros may be redefined during the assembly 
by introducing a new macro definition for that name. 
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Define General Register Equates 


* Easy to do this with a macro like 


GRE 
.* Similarly for GR1 — GR14 
GR15 


¢ A simple variation with a conditional-assembly loop: 


MACRO 

GREGS 

LCLA 8&N Define a counter variable 
ANOP 

EQU 8N 

SETA 8&N+1 Increment 8&N by 1 

AIF (8% LE 15).X Repeat for all registers 1-15 
MEND 
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Example: Defining Equated Symbols for Registers 


To illustrate a basic form of macro, suppose you wish to generate a sequence of EQU state- 
ments to define symbolic names GRO, GR1, ..., GR15 for referring to the sixteen General 
Purpose Registers. A call to the GREGS macro will do this: 


OoOoOn mgm op WDM F © 


Figure 14. Simple Macro to Generate Register Equates 


Then, a call to the GREGS macro will define the desired equates, by inserting the sixteen 
model statements into the statement stream. 


The macro definition can be made more compact by using conditional assembly statements 
to form a simple loop inside the macro: 
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&N Define a counter variable 


&N 
&N+1 Increment &N by 1 
(&N LE 15).X Repeat for all registers 1-15 


Figure 15. Macro to Generate Register Equates Differently 


Macro Parameters and Arguments 


* .. Distinguish parameters from arguments: 

* Parameters are 
- declared on macro definition prototype statements 
- always local variable symbols 


- assigned values by association with the arguments of macro calls 


Arguments are 
- supplied on a macro instruction (macro call) 
- almost any character string (typically, symbols) 


- providers of values to associated parameters 
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Macro Parameters and Arguments 
In the following discussion, we will distinguish parameters from arguments, as follows: 
e Parameters are 
-— . declared on the prototype statements of macro definitions 
—- always local variable symbols 
— assigned values by being associated with the arguments of a macro instruction 
—- sometimes known as “dummy arguments” or “formal parameters”. 
e Arguments are 
—- supplied on a macro instruction statement (“macro call”) 
- almost any character string (typically, symbols) 
— the providers of values to the corresponding associated parameters 


— sometimes known as “actual arguments” or “actual parameters”. 
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Macro-Definition Parameters 


Declared on the prototype statement 


— aS operands, and as the name-field symbol 
All macro parameters are (“read-only”) local variable symbols 


Parameters usually declared in exactly the same order as the 
corresponding actual arguments will be supplied on the macro call 


~ Exception: keyword-operand arguments 
- Declared by writing an equal sign after the parameter name 
- Can provide default keyword-parameter value on prototype statement 


Parameters example: one name-field, two positional, one keyword 


MACRO 
&Name MYMAC3 &Paraml,&Param2,&KeyParm=YES 
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Macro-Definition Parameters 


The parameters in a macro definition are declared by virtue of their appearing as operands 
(and the name-field symbol) on the prototype statement. These declared parameters are var- 
lable symbols! Usually, they are declared in exactly the same order as the corresponding 
actual arguments will be supplied on the macro call. 


' The exception is keyword arguments: they are declared by writing an equal sign after the 
parameter name. You can also provide a default value for a keyword parameter on the pro- 
totype statement, by placing that value after the equal sign. When the macro is called, the 
argument values for keyword parameters are supplied by writing the keyword parameter 
name, an equal sign, and the value, as an operand of the macro call. 


For example, suppose we write a macro prototype statements as shown in Figure 16: 


MACRO 
MYMAC3 &Param1, &Param2, &KeyParm=YES 


MEND 


Figure 16. Sample Macro Prototype Statement 


The prototype statement defines a name-field parameter (&Name), two positional parameters 
(&Paraml1,&Param2), and one keyword parameter (&KeyParm) with a default value YES. 


Unlike positional arguments and parameters, keyword arguments and parameters may 


appear in any order, and may be mixed freely among the positional items on the prototype 
statement and the macro call. 
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Macro-Instruction Arguments 


e Arbitrary strings (with some syntax limitations) @ 
- Most often, just ordinary symbols 


- “Internal” quotes and ampersands in quoted strings must be paired 


Separated by commas, terminated by blank (like ordinary Assembler 
Language) 


- Comma and blank must otherwise be quoted 
Omitted (null) arguments are recognized, and are valid 
Examples: 


MYMACI A,, ‘String' 2nd argument omitted 
MYMAC1 Z,RR,'Testing, Testing’ 3rd argument with comma and blank 
MYMAC1 A,B,'Do''s, && Don''ts' 3rd argument with everything... 
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Macro-Instruction Arguments 


50 


The arguments of a macro instruction are the name-field entry and the operands. They may 
be arbitrary strings of characters, with some syntax limitations such as requiring strings con- 
taining quotes and ampersands to contain pairs of each. Most often, the operands will be 


just symbols (literals are allowed in almost all circumstances). 


The operands are separated by commas, and terminated by a blank (conforming to the | & 


normal Assembler Language syntax rules). If the argument string is intended to contain a 
comma or a blank, they must be quoted. 


Omitted (null) arguments are perfectly acceptable. 


To illustrate, suppose a macro named MYMAC‘1 expects three positional arguments. Then in 
the following example, 


MYMAC1 A,,'String' end argument omitted 
MYMAC1 Z,RR, ‘Testing, Testing' 3rd argument with comma and blank 
MYMAC1 A,B,'Do''s, & Don''ts' 3rd argument with everything... 
the first call omits the second argument; the second call has a quoted character string con- 
taining an embedded comma and quote as its third argument; and the third call has a 
variety of special characters in its quoted-string third argument. 
Pairs of quotes or ampersand characters are required within quoted strings used as macro : 
arguments, for proper argument parsing and recognition. These characters are not con- 


densed into a single character when the argument is associated (“passed”) to the corre- 
sponding symbolic parameter. 
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Macro Parameter-Argument Association 
* Three ways to associate (caller’s) arguments with (definition’s) 
parameters: 
by position, referenced by declared name (most common way) 
by position, by argument number (using &SYSLIST notation) 
by keyword: always referenced by name, arbitrary order 
~- Argument va/ues supplied by writing keyname=valiue 


Example 1: (Assume prototype statement as on foil 41) 


&Name MYMAC3 &Paraml, &Param2, &KeyParm=YES Prototype 
Labl MYMAC3 X,Y,KeyParm=N0 Call: 2 positional, 1 keyword argument 


* Parameter values: &Name = Labl 
i &KeyParm = NO 

x &Paraml = X 
* 


&Param2 = Y 
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Macro Parameter-Argument Association ... 


¢ Example 2: 


Lab2 MYMAC3 A Call: 1 positional argument 


* Parameter values: &Name = Lab2 
&KeyParm = YES 

ba &Paraml =A 

* &Param2 = (null) 


Example 3: 


MYMAC3 - -H,KeyParm=MAYBE,J Call: 2 positional, 1 keyword argument 


* Parameter values: &Name = (null) 
~ &KeyParm = MAYBE 
e &Paraml = H 
ba &Param2 = J 
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Macro Parameter-Argument Association 


There are three ways to associate arguments with parameters: 


1. 


by position, referenced by the declared positional parameter name (this is the most 
usual way for macros to refer to their arguments) 


by position and argument number (using the &SYSLIST system variable symbol, which 
will be discussed in “Macro-Instruction Argument Lists and the &SYSLIST Variable 
Symbol” on page 63) 
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3. by keyword: keyword arguments are always referenced by name, and the order in which 
they appear is arbitrary. Values provided for keyword arguments override default 
values declared on the prototype statement. 

To illustrate, consider the examples in Figure 17. Assuming the same macro definition pro- 


totype statement shown in Figure 16 on page 49, the resulting values associated with the 
parameters are as shown: 


Labl MYMAC3 X,Y,KeyParm=NO 2 positional, 1 keyword argument 


Parameter values: &Name &KeyParm = NO 
&Paraml &Param2 = Y 


Lab2 MYMAC3 A 1 positional argument 


Parameter values: &Name Lab2 &KeyParm = YES 
&Paraml = A &Param2 (nul1) 


MYMAC3 H,KeyParm=MAYBE, J 2 positional, 1 keyword argument 


Parameter values: &Name (null) &KeyParm = MAYBE 
&Paraml = H &Param2 J 


Figure 17. Macro Parameter-Argument Association Examples 


In the third example, observe that the keyword argument KeyParm=MAYBE appears between the 
first and second positional arguments. 


e: . +43 -The Ada™ programming language is the first major high-level language to support keyword parame- 
ters and arguments. Assembler Language programmers have been using them for decades! 


52 High Level Assembler Tutorial Guide 


Generating a Byte Sequence: BYTESEQ1 Macro 


¢ ' BYTESEQ1 generates a byte for each value 


MACRO 
&L BYTESEQ1 &N 
.* BYTESEQ] -- generate a sequence of byte values, one per statement. 
-* No checking or validation is done. 
L &K 


C &L' EQ '').Loop Don't define the label if absent 


&L ALI Define the label (if present | 
. Loop 
® &K &K+1 Increment &Kk 


(&K ae Done Check for termination condition 
& 


Cont inue 
- Done 


* Two test cases 


BSla  BYTESEQI 5 
BYTESEQ1 1 
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Example: Generating a Byte Sequence 


We can write a macro with a single parameter to generate a sequence of bytes, using the 
same techniques as the conditional-assembly example given in Figure 4 on page 27. 


MACRO 
© &L BYTESEQ1 &N 
.* BYTESEQ]1 -- generate a sequence of byte values, one per statement. 
-* No checking or validation is done. 
LclA &K 
('BL' EQ '').Loop Don't define the label if absent 
OX Define the label 


&K+] Increment &K 
(&K GT &N).Done Check for termination condition 
A11(&K) 


Continue 
.Done 
* Two test cases 
BSla BYTESEQ] 5 
BYTESEQ] 1 


Figure 18. Macro to Define a Sequence of Byte Values 


° This macro generates a separate DC statement for each byte value. As we will see later, it 
has some limitations that are easy to fix. 
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Macro Parameter Usage 46 


¢ Values supplied by arguments in the macro instruction (“call”) are 
substituted as character strings 


Values may be substituted in name, operation, and operand fields of 
model statements 


- Substitutions ignored in remarks fields and comment statements 
— Can sometimes play tricks with operand fields containing blanks 


- Some limitations on which opcodes may be substituted 


Some constraints on substitutions in conditional assembly statements 


~- Because the assembler has to understand basic.macro structures at the 
time it encodes the macro 
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Macro Parameter Usage 


Values are assigned to macro parameters from the corresponding arguments on the macro- 
instruction statement, either by position in left-to-right order (for positional arguments), or by 
name (for keyword arguments). These are then substituted as character strings into model 
statements (wherever points of substitution marked by the parameter variable symbols 
appear). The points of-substitution in model statements may be in the 


e name field 
¢ operation field 
e operand field 


but not in the remarks field, nor in comment statements. (For some operations, it is possible 
to construct an operand string containing embedded blanks followed by “remarks” into 
which substitutions have been done. We will leave as an exercise for the reader the delights 
of discovering how to do this.) 


Substitutions are not allowed in some places in conditional or ordinary assembly statements 
such as COPY, REPRO, MACRO, and MEND, because the assembler must know some infor- 
mation about the basic structure of the macro definition (and of the entire source program!) 
at the time it is encoded. For example, substituting the string MEND for an operation code in 
the middie of a macro definition could completely alter that definition! 
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Macro Expansion and MEXIT 


© ¢ Macro expansion or generation 


¢ Initiated by recognition of a macro instruction 


Assembler suspends current activity, begins to “execute” or 
“interpret” the encoded definition 


- Parameter values assigned from associated arguments 

- Conditional assembly statements interpreted, variable symbols assigned 
values 

- Model statements substituted, and output to base language processor 


Generated statements scanned for inner macro calls 


~ Recognition of inner calls suspend current-expansion, start new one 


Expansion terminates when MEND or MEXIT is interpreted 
-  MEXIT is equivalent to “AGO to MEND” (but quicker) 
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Macro Expansion and the MEXIT Statement 


When the assembler recognizes a macro instruction, macro expansion or macro generation 
is initiated. The assembler suspends its current activity, and begins to “execute” or “inter- 
pret” the encoded definition of the called macro. 


; 7 - During expansion, the first step is to assign parameter values from the associated argu- 
& ments on the macro call. Subsequently, conditional assembly statements are interpreted, 
. '. variable symbols are assigned values, model statements are substituted, and text is output 
to the base language processor. 


The generated statements are scanned for inner macro calls; recognition of an inner call 
suspends the current expansion, and starts a new one for the newly-recognized inner macro. 


Expansion of a macro terminates when either the MEND statement is reached, or when an 
expansion-terminating macro-exit MEXIT statement is interpreted. (MEXIT is equivalent to an 
“AGO to MEND” statement, but is quicker to execute.) 


Macros 55 


Macro Argument Attributes and Structures 


¢ Assembler Language provides some simple mechanisms to “ask 
questions” about macro arguments 


° 6 Built-in functions, called attribute references 


- Most common questions: “What is it?” and “How big is it?” 


¢ Determine properties (attributes) of the actual arguments 


- Provides data about possible base language properties of symbols: 
Type, Length, Scale, Integer, and Defined attributes 


¢ Decompose argument structures, especially parenthesized lists 


- Use Number (N') and Count (K') attribute references 
— Determine the number and nesting of argument list structures 
— Determine the count of characters in an argument 
Extract sublists or sublist elements 
- Use substring and concatenation operations to parse list items 
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Macro Argument Attributes and Structures 


Among the elegant features of the Assembler Language are some simple mechanisms 

(built-in functions, called attribute references) that allow you to determine some properties 

(i.e., attributes) of the actual arguments. For example, attribute references provide informa- 

tion about possible base language (ordinary assembler language) use of the symbols: what 
_kinds of objects they name, what is the length attribute of the named object, etc. 


Three major classes of “inquiry facilities” are provided: 


1. The type attribute reference (T') allows you to ask “What base-language meaning is 
attached to it?” about a macro argument. The value of the type attribute reference (a 
single character; only the type attribute reference has character values) can tell you 
whether the argument is 


* asymbol that names data, machine instructions, macro instructions, sections, etc. 
¢ a self-defining term (binary, character, decimal, or hexadeimal) 
e an “unknown” type. 


2. The “mechanical” or “physical” characteristics of macro arguments can be determined 
by using 


¢ two attribute references: Count (K') supplies the actual count of characters in the 
~ argument, and Number (N') tells you how many elements appear in an argument 
list structure. 


e  fist-structure referencing and decomposition operations, involving subscripted refer- 
ences to parameter variable symbols. 


A rather sophisticated list scanning capability is provided to help you decompose 
argument structures, especially parenthesized lists. With this notation, you can 


- determine the number and nesting of all such list structures 


—- extract any sublists or sublist elements 


56 High Level Assembler Tutorial Guide 


- use the usual substring and concatenation operations to manipulate portions of 
lists and list elements. 


| 3. The base-language attributes of macro arguments can be determined by using any of 
four attribute references: Length (L'), Scale (S'), Integer (I'), and Defined (D'). All four 
have numeric values. 


Macro Argument Attributes: Type 


¢ Type attribute reference (T') answers 
- “What is it?” 


« - “What meaning might it have in the base language?” 


Assume the following statements in a program: 


And, assume the following prototype statement for MACTA: 


MACTA &P1,&P2,..., etc. 
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Macro Argument Attributes: Type ... 


&@ ¢ Then a call to MACTA like 


Zz MACTA A,B,C,D,C'A',,'?',2 Call MACTA with various arguments 


¢ would provide these type attributes: 


T'SPl 
T'&P2 
T'&P3 
T'&P4 
T'&P5 
T'&P6 
T'&P7 
T'&P8 = 
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"~A' 
'F* 
is a 
'y° 
‘ne 
‘9' 
'y' 
"' 


aligned, implied-length address 

aligned, implied-length fullword binary 
aligned, implied-length short floating-point 
machine instruction statement 

See eat term 

omitted (null) 

unknown 

macro instruction statement 
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: Macro-Instruction Argument Properties: Type Attribute 


The type attribute reference is often the first used in a macro, to help the macro determine 
“What is it?”. More precisely, it tries to answer the question “What meaning might this argu- 
ment string have in the base language?” It typically appears in conditional assembly state- 


ments like these: 
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AIF (T'&Paraml eq '0').Omitted Argument is null 
AIF (T'&Paraml eq 'U').Unknown Unknown argument type 


‘To illustrate some of the possible values returned by a type attribute reference, assume the & 
following statements appear in a program: 

A DC A(*) 

B DC F'10! 

C DC E'2,71828' 

D MVC =OA,B ‘ 


If the same program contains a macro named MACTA with positional arguments 
&P1,&P2,...,etc., and if MACTA is called with the following arguments, then a type attribute 
reference to each of the positional parameters would return the indicated values: 


Z MACTA A,B,C,D,C'A',,'?',2 Call MACTA with various arguments 


T'&P1 = 'A' aligned, implied-length address 

T'&P2 = 'F! aligned, implied-length fullword binary 
T'&P3 = 'E' aligned, implied-length short floating-point 
T'&P4 = ‘YT! machine instruction statement 

T'&P5 = 'N! self-defining term 

T'&P6 = ‘0! omitted (null) 

T'&P7 = 'U! unknown 

T'&P8 = 'M! macro instruction statement 


There are 28 possible values that might be returned by a type attribute reference. 
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: | Macro Argument Attributes: Count 51 


¢ Count attribute reference (K') answers “How many characters in an 
argument?” 


¢ Suppose we have a macro with prototype statement 


MACS &P1,&P2,8P3,...,8K1=,&K2=,8K3=,... 


¢ This macro instruction would give these count attributes: 


MACS A,BCD, 'EFGH', ,K1=5,K3==F'25' 


K'&P1 = 1 corresponding to A 
K'&P2 = 3 ABC 
K'&P3 = 6 "DEFG' 
K'&P4 = 6 (nul1) 
K'&K1 = 1 5 
K'&K2 = 6 (null) 
K'&K3 = 6 =F'25' 
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Macro-Iinstruction Argument Properties: Count Attribute 


A macro argument has one irreducible, unavoidable property: the count of the number of 
characters it contains. These can be determined for any argument using the count attribute 
reference, K'. For example, if MAC8 has positional parameters &P1, &P2, ..., etc., and 
keyword parameters &K1, &K2, ..., etc., then for a macro instruction statement such as the 


© following: 


we would find that 


MACB A,BCD,'EFGH', ,K1=5,K2=,K3==F'25! 


K'&P1 = 1 corresponding to A 
K'&P2 = 3 ABC 
K'&P3 = 6 'DEFG' 
K'&P4 = 0 (null) 
K'&K1 = 1 5 
K'&K2 = 0 (null) 
K'&K3 = 6 =F'25! 
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Macro Argument Attributes: Number 52 


¢ Number attribute reference (N') answers “How many items in a list?” 
¢ List: a parenthesized sequence of items separated by commas 


Examples: (A) (B,C) (D,E,,F) 


List items may themselves be lists, to any nesting 


Examples: ((A)) (A, (B,C) (A, (B,C, (D,E,,F),G),H) 


Subscripts on parameters refer to argument list (and sublist) items 


- Each added subscript references one nesting level deeper 


N' also determines maximum subscript used with a subscripted 
variable symbol | 
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Macro Argument List Structure Examples 


¢ Assume the same macro prototype as in foil 51: 


MACS &P1,&P2,8P3,...,&Kl=,&K2=,&K3=,... Prototype 
MACS (A),A,(B,C),(B,(C, (D,E))) Sample macro call 


° Then, the number attributes and sublists are: 


list of 1 item, A 
tA is not a list 
A is not a list 
list of 2 items, B and C 
(B is not a list) 
list of 2 items, B and (C,(D,E)) 
list of 2 items, C and (D,E) 
list of 2 items, D and £ 
N'&P4(2,2 (? is not a list 
&P4(2,2,2 N'&P4(2,2 E is not a list 
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Macro-Instruction Argument Properties: Number Attribute 


A list is a parenthesized sequence of items, separated by commas. The following are exam- 
ples of lists: 


(A) (B,C) (D,E, )F) 


Figure 19. Macro Argument List Structures 


List items may themselves be lists (which may in turn contain lists, and so forth). Examples 
of lists containing sublists are: 
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((A)) (A, (B,C)) (A, (B,C, (D, E, 5F) 5G) JH) 


Lists may have any number of items, and any level of nesting, subject only to the constraint 
that the size of the argument may not exceed 255 characters. 


The number attribute reference (N') is used to determine the number of elements in a list or 

sublist, or the number of elements in a subscripted variable symbol. For example, if the 

three lists in Figure 19 on page 60 were arguments associated with parameters &P1, &P2, 

and &P3 respectively, then a number attribute reference to each parameter would return the 
° following values: | 


N'&P1 = 1 (A) is a list of 1 item 
. N'&P2 = 2 (B,C) is a list of 2 items 
N'&P3 = 4 (D,E,,F) is a list of 4 items; the third is null 
&Z(17) = 42 set an element of a subscripted variable symbol 
N'&Z2 = 17 maximum subscript on &Z is 17 


Sublists 


It is sometimes useful to pass groups of related argument items as a single unit, by grouping 
them into a list. This can save the effort needed to name additional parameters on the 
macro prototype statement, can can simplify the documentation of the macro call. 


To extract list items from argument lists and sublists within a macro, subscripts are attached 
to the parameter name. For example, if &P is a positional parameter, and N'&P is not zero 
(meaning that the argument associated with &P is indeed a list), then &P(1) is the first item in 
the list, &P(2) is the second, and &P(N'&P) is the last item. 


To determine whether any list item is itself a list, we use another number attribute refer- 
ence. For example, if &P(1) is the first item in the list argument associated with &P, then 

| - -N'&P(1) is the number of items in the sublist associated with &P(1). For example, if argument 
((X,Y),Z,T) is associated with &P, then 


N'8P 8 = 3 items are (X,Y), Z, and T 
N'&P(1) = 2 items are X and Y 


As list arguments become more deeply nested, the number of subscripts used to refer to 
their list items also increases. For example, &P(1,2,3) refers to the third item in the sublist 
appearing as the second item in the sublist appearing as the first item in the list argument 
associated with &P. Suppose MAC8 has positional parameters &P1, &P2, ..., etc., then fora 
macro instruction statement such as the following: | 


MAC8 = (A) ,A, (B,C), (B, (C, (D,E) )) Sample macro call 


&P1 = (A) N'&P1 = 1 list of 1 item, A 
&P1(1) = A N'&P1(1) =1 (A jis not a list) 
&P2 =A N'&P2 =1 (Ais not a list) 
. &P3 = (B,C) N'&P3 =2 list of 2 items, B and C 
&P3(1) = B N'&P3(1) = 1 (Bis not a list) 
&P4 = (B,(C,(D,E))) N'&P4 = 2 list of 2 items, B and (C,(D,E)) 
&P4(2) = (C,(D,E)) N'&P4(2) =2 list of 2 items, C and (D,E) 
° &P4(2,2) = (D,E N'&P4(2,2) =2 list of 2 items, D and E 
&P4(2,2,1) = D N'&P4(2,2,1) = 1 (Dis not a list) 
&P4(2,2,2) = E N'&P4(2,2,2) = 1 (E is not a list) 


There is an oddity in the assembler’s interpretation of the number attribute for items which 
are not themselves lists. As can be seen from the first two samples above, both '(A)' and 
'A' return a number attribute of 1. The assembler will treat parameter references &P and 

&P(1) as the same string if the argument corresponding to &P is not a properly formed list. 
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This means that if it is important to know whether or not a list item is in fact a parenthesized 
list, you will need to test the first and last characters to verify that the list is properly 
enclosed in parentheses. 
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Macro Argument Lists and &SYSLIST 


e &SYSLIST(k): a “synonym” for the k-th positional parameter 


- Whether or not a named positional parameter was declared 


° N'&SYSLIST = number of all positional arguments 


* Assume a macro prototype MACNP (with or without parameters) 


Then these arguments would have Number attributes as shown: 


MACNP A,(A),(C,(D,E,F)), (YES,NO) 


N'&SYSLIST = 4 MACNP has 4 arguments 

N'SSYSLIST(1 =] &SYSLIST(1 = A (A 1s not a list) 
W'SSYSLIST(2 =] &SYSLIST(2 = (A) is a list with 1 item 
W'S&SYSLIST(3 = 2 &SYSLIST(3 = (C,(D,E,F)) is a list with 2 items 
N'&SYSLIST(3,2) = 3 &SYSLIST(3,2) = (D,€,F) is a list with 3 items 
N'&SYSLIST(3,2,1) = 1 &SYSLIST(3,2,1) = D (D is not a list) 
N’&SYSLIST(4) = 2 &SYSLIST(4) = (YES,NO) is a list with 2 items 
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Macro-Instruction Argument Lists and the &SYSLIST Variable Symbol 


It is frequently useful to be able to call a macro with an indefinite number of arguments that 
we intend to process “identically” or “equivalently”, so that no particular benefit is gained 
from naming and referring to each one individually. | 
© The system variable symbol &SYSLIST can be used to refer to the positional elements of the 
argument list: &SYSLIST(k) refers to the k-th positional argument, whether or not a corre- 
sponding positional parameter was declared on the macro’s prototype statement. The total 
number of positional arguments in the macro instruction’s operand list can be determined 
using a Number attribute reference: N'&SYSLIST is the number of positional arguments. 


No other reference to &SYSLIST can be made without subscripts. Thus, it is not possible to 
refer to all the arguments (or to all the positional parameters) as a group using a single 
unsubscripted reference to &SYSLIST. 

To illustrate the use of &SYSLIST references, suppose we have defined a macro named 


MACNP; whether or not any positional parameters are declared doesn’t matter for this 
example. If we write the following macro call: 


MACNP A,(A),(C, (D,E,F)), (YES,NO) 


then the number attributes of the &SYSLIST items, and their values, are the following: 


N'&SYSLIST = 4 MACNP has 4 arguments 

N'&SYSLIST(1) =] &SYSLIST (1) = A (A is not a list) 

N'&SYSLIST(2) = ] &SYSLIST (2) = (A) is a list with 1 item 
af N'&SYSLIST (3) = 2 &SYSLIST (3) = (C,(D,E,F)) is a list with 2 items 

N'&SYSLIST(3,2) = 3 &SYSLIST(3,2) = (D,E,F) is a list with 3 items 

N'&SYSLIST(3,2,1) = 1 &SYSLIST(3,2,1) =D (D is not a list) 

N'&SYSLIST (4) =2 &SYSLIST(4) = (YES,NO) is a list with 2 items 


Observe that references to sublists are made in the same way as for named positional 


parameters. One additional (leftmost) subscript is needed for &SYSLIST references, because 
that parameter is being referenced by number rather than by name. 
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Global Variable Symbols 


SRR ER a IT GP GS TS SGA IIE SSSI I EL LESS TE TT EE IN PT ON I a EE EI TE I EE ED 
° Macro calls have one serious defect: 

Can't assign (i.e. return) values to arguments 

unlike most high level languages 


communication with the interior of a macro is “one-way”: arguments in, 
statements out 


no “functions” (i.e. macros with a value) 


Values to be shared among macros (and/or with open code) must use 
global variable symbols 


- Scope: available to all declarers 


- Can use the same name as a local variable in a scope that does not 
declare the name as global 


' -One macro can create (multiple) values for others to use 
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Global Variable Symbols 


Thus far, our macro examples have been self-contained: all their communication with the 
“outside world” has been through their argument lists and the statements they generated. 


In the System/360/370/390 Assembler Language, macro calls have one serious omission: 
they can’t assign (i.e. return) values to arguments, unlike most high level languages. That is, 
all macro arguments are “input only”. Thus, communication with the interior of a macro by 
way of the argument list appears to be “one-way”: arguments go in, but only statements 
come out. 


Furthermore, there is no provision for defining “functions” (that is, macros which return a 
value associated with the macro name itself). 


Thus, values to be shared among macros (and/or with open code) must use a different 
mechanism, that of global variable symbols. The scope rule for global variable symbols is 
simple: they are shared by and are available to all declarers. (You may of course use the 
Same name as a local variable in a scope that does not declare the name as global.) 


With an appropriate choice of named global variable symbols, one macro can create single 
or multiple values for others to use. 


The “dictionary” or “pool” of global symbols has similar behavior to certain kinds of external 
variables in high level languages, such as Fortran COMMON: all declarers of variables in 
COMMON may refer to them. However, the assembler imposes no conformance rules of 
ordering or size on declared global variable symbols; you simply declare the ones you need, 
and the assembler will figure out where to put them so they can be shared with other 
declarers. (Unlike most high-level languages, sharing of global variable symbols is purely 
by name!) 
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Variable Symbol Scope Rules: Summary 56 


© ¢ Global Variable Symbols 


Available to all declarers of those variables on GBLx statements (macros 
and open code) 


Arithmetic, boolean, and character types; may be subscripted 


Values persist through an entire assembly 


— Values kept In a single, shared, common dictionary 


Values are shared by name 
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Variable Symbol Scope Rules: Summary ... 


¢ Local Variable Symbols 
Explicitly and implicitly declared local variables 
Symbolic parameters 
— Values are “read-only” 


Local copies of system variable symbols whose value is constant 
throughout a macro expansion 


— « Values kept in-a local, transient dictionary 
— Created on macro entry, discarded on macro exit 


— Recursion still implies a separate dictionary for each entry 


Open code has its own local dictionary 
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Variable Symbol Scope Rules: Summary 


At this point, we will summarize the scope rules for variable symbols. 


e Global Variable Symbols are available to all macros and open code that have declared 
the symbols as GBLx. The three types denoted by “x” are as for local variable symbols: 
Arithmetic, Boolean, and Character. 


e e The values of global variable symbols persist through an entire assembly, and their 
values are kept in a single, common dictionary. 


e Local variable symbols include explicitly and implicitly declared variables, symbolic 
parameters, and local copies of system variable symbols whose value is constant 
throughout a macro expansion. They are not shared with other macros, or with open 
code (and vice versa). Open code has its own local dictionary, which is active 
throughout an assembly. 
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¢ Variable symbol values are kept in a local, transient dictionary that is created on macro 
entry, and discarded on macro exit. The symbols are treated as “read-only”, meaning 
that their values are constant throughout a macro, and cannot be changed. Note that 
recursion still implies a separate dictionary for each entry to the macro; every invoca- 
tion has its own non-shared dictionary. 


Debugging Macros 


* Complex macros can be hard to debug 
- Written in a difficult, unstructured language 


¢ Some useful debugging facilities are available: 


- MNOTE statements 


— Can be inserted liberally to trace control flows and display values 


MHELP statements nel a cordicate fox be beutl, 


— Built-in assembier trace and display facility Cen bess £ 
— Many levels of control; can be quite verbose! 

ACTR statement 

— Limits number of conditional branches within a macro 


— Very useful if you suspect excess looping 
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Macro Debugging Techniques 


No discussion of macros would be complete without some hints about debugging them. The 
macro language is complex and not well structured, and the “action” inside a macro is gen- 
erally hidden because each statement is not “displayed” as it is interpreted by the condi- 
tional assembly logic of the assembler. 


We will briefly describe three statements useful for macro debugging: MNOTE, MHELP, and 
ACTR. 
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MNOTE Statements 


/* MNOTE allows the most detailed controls over debugging output 
- You specify exactly what to display, and where 


MNote *, ‘At Skipl9: &&VG = &VG., S&TEXT = ‘''&TEXT''' 


~- You can control which ones are active (with global variable symbols) 


Gb1B &DEBUG(26) 


AIF (NOT &DEBUG(7)) .Skip19 
MNote *,'At Skipl19: &&VG = &VG., S&TEXT = ‘'&TEXT''' 
-Skip19 ANop 


- You can “disable” MNOTEs with conditional-assembly comments 


— MNote *,'At Skipl9: &&VG = &VG., S&TEXT = ‘'&TEXT''' 
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MNOTE Statements 


We have already touched on the use of MNOTE statements in “The MNOTE Statement” on 
page 8. Their main benefits for debugging macros are: 


MNOTE statements may be placed at exactly those points where the programmer knows 
that internal information may be most useful, and exactly the needed items can be dis- 
played. 7 


~ The MNOTE message text can provide specific indications of the internal state of the 


macro at that point, and why it is being provided. 


Though it requires additional programming effort to insert MNOTE statements in a 
macro, they can be left “in place”, and enabled or disabled at will. Typical controls are 
as simple as “commenting out” the statement (with a “.*” conditional-assembly 
comment) to adding global debugging switches to control which statements will be exe- 
cuted, as illustrated here: 


Gb1B &DEBUG(20) 


AIF (NOT &DEBUG(7)).Skip19 
MNote *,'At Skipl19: &&VG = &VG., &&TEXT = ''&TEXT'!! 
~Skip19 ANop 


If the debug switch &DEBUG(7) is 1, then the MNOTE statement will produce the specified 
output. 
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The MHELP Statement 


MHELP controls flow tracing and variable “dumping” 
MHELP operand value is sum of 8 bit values: 


Trace macro calls (name, depth, &SYSNDX value) 

Trace macro branches (AGO, AIF) 

AIF dump (dump scalar SET symbols before AIFs) 

Macro exit dump (dump scalar SET symbols on exit) 

Macro entry dump (dump parameter values on entry) 

Global suppression (suppress GBL symbols in AIF, exit dumps) 
Hex dump (SETC and parameters dumped in hex and EBCDIC) 
MHELP suppression (turn off all active MHELP options) 


Best to set operand with a GBLA symbol (can save/restore its value), or 
from &SYSPARM value 


Can also limit total number of macro calls (see Language Reference) 
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The MHELP Statement 
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The MHELP statement is more general but less specific in its actions than the MNOTE state- 
ment. Once an MHELP option is enabled, it stays active until it is reset. The MHELP operand 
specifies which actions should be activated; the value of the operand is the sum of the “bit 
values” for each action: 


1 Trace macro calls 


MHELP 1 produces a single line of information, giving the name of the called 
macro, its nesting level, and its &SYSNDX number. This information can be used 
to trace the flow of control among a complex set of macros, because the 
&SYSNDX value indicates the exact sequence of calls. 


2 Trace macro branches 


The AIF and AGO branch trace provides a single line of information giving the 
name of the macro being traced, and the statement numbers of the model state- 
ments from which and to which the branch occurs. (Unfortunately, the target 
sequence symbol name is not provided, nor is branch tracing active for library 
macros. This latter restriction can be overcome by using the LIBMAC option: if 
you specify LIBMAC, tracing is active for library macros. 


4 AIF dump 


When MHELP 4 is active, all the scalar (undimensioned) SET symbols in the 
macro dictionary (i.e., explicitly or implicitly declared in mg macro) are displayed 
before each AIF statment is interpreted. 


8 Macro exit dump 


MHELP 8 has the same effect as the preceding (MHELP 4), but the values are 
displayed at the time a macro expansion is terminated by either an MEXIT or 
MEND statement. 


16 Macro entry dump 


MHELP 16 displays the values of the symbolic parameters passed to a macro at 
the time it is invoked. This information can be very helpful when debugging 
‘macros that create or pass complex arguments to inner macros. 
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32 Global suppression 


Sometimes you will use the MHELP 4 or MHELP 8 options to display variable 
symbols in a macro that has also declared a large number of scalar global 
symbols, and you are only interested in the local variable symbols. Setting 
MHELP 32 suppresses the display of the global variable symbols. 


64 Hex dump 


When used in conjunction with any of MHELP’s “display” options (MHELP 4, 8, 
and 16), causes the value of displayed SETC symbols to be produced in both 
character (EBCDIC) and hexadecimal formats. If you are using character string 
data that contains non-printing characters, this option can help with under- 
standing the values of those symbols. 


128 MHELP suppression 


Setting MHELP 128 will suppress all currently active MHELP options. (MHELP 0. 
will do the same.) 


'- - These values are additive: you may specify any combination. Thus, 


MHELP 1+2 Trace macro calls and AIFs 
will request both macro call tracing and AIF branch tracing. 


As you might infer from the values just described, these MHELP “switches” fit in a single 
byte. The actions of the MHELP facility are controlled by a fullword in the assembler, of 
which these values are the rightmost byte. The remaining three high-order bytes can be 
used to control the maximum number of macro calls allowed in an assembly; the details are 
described in the IBM High Level Assembler/MVS & VM & VSE Language Reference manual. 


The output of the MHELP statement can sometimes be quite voluminous, especially if mul- 
-tiple traces and dumps are active. It is particularly useful in situations where the macro(s) 
-- you are debugging were ones you didn’t write, and in which you cannot conveniently insert 
MNOTE statements. Also, if macro calls are nested deeply, the MHELP displays can help 
with understanding the actions taken by each inner macro. 


To provide some level of dynamic control over the MHELP options in effect, it is useful to set 
a global arithmetic variable outside the macros to be traced, and then refer to that value 
inside any macro where the options might be modified; the MHELP operand can then be 
saved in a local arithmetic value, and restored to its “global” value on exit. Another useful 
technique is to derive the MHELP operand from the &SYSPARM string supplied to the 
assembler at invocation time; this lets you debug macros without making any changes to the 
program’s source statements. 
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The ACTR Statement 


¢ ACTR specifies the maximum number of conditional-assembly 
branches in a macro or open code 


ACTR 266 Limit of 268 successful branches 


Scope is local (to open code, and to each macro) 


— Can set different values for each; default is 4096 
Count decremented by 1 for each successful branch 


When count goes negative, macro’s invocation is terminated 


Executing erroneous conditional assembly statements halves the 
ACTR value! | 


an Following statement has syntax errors 
&J SET) &J+? If executed, would cause ACTR = ACTR / 2 
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The ACTR Statement 
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The ACTR statement can be use the limit the number of conditional assembly branches (AIF 
and AGO) executed within a macro invocation (or in open code). It is written 


ACTR arithmetic_expression 


where the value of the “arithmetic_expression” will be used to set an upper limit on the 
~ number of branches’ executed'by the assembler. In the absence of an ACTR statement, the 
default ACTR value is 4096, which is adequate for most macros. 


ACTR is most useful in two situations: 


1. If you suspect a macro may be looping or branching excessively, you can set a lower 
ACTR value to limit the number of branches. 


2. If avery large or complex macro must make a large number of branches, you can set 
an ACTR value high enough that all normal expansions can be handled safely. 
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Macro Techniques 


Macros as a Higher Level Language 


* Can be written to perform very simple to very complex tasks 


~ Housekeeping (register saving and restoring, calls, define symbols, map 
data structures) 
- Define your own application-specific languages 


Macros can provide much of the “goodness” of HLLs 


Abstract data types, private data types 
information hiding, encapsulation 
Avoiding side-effects 

Polymorphism 


-Macro sets can be built incrementally to suit application needs 
Can develop “application-specific languages” 


Avoid struggling with the latest “universal language” fad 


~- Add new capabilities to existing applications without converting 
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Macro instructions (or macros for short) provide the Assembler Language programmer with 
a wonderfully flexible set of possibilities. Macros share many of the properties of ordinary 
: _. subroutines that can be called from many different applications: once written, they may be 
© a used for-many other tasks: Their capabilities range from the very simple: 


e perform “housekeeping” such as saving registers, making subroutine calls, and 
restoring the registers and returning (the operating system supplies the SAVE, CALL, 
and RETURN macros for these functions) 


e define symbols for registers and fixed storage areas, and declare data structures to 
define or map certain system control blocks used by programs to communicate with the 
operating system (macros such as REGEQU, DCB, and DCBD) 


to the very complex: 


e macros have been written to define “artificial languages” in which entire applications 
are written (examples include the SNOBOL4 language, and certain banking and tele- 
processing applications). 


Part of our purpose here will be to show that you can write macros to simplify almost any 
part of the programming process, from the simplest and smallest to the very complex and 


powerful. 


Higher-level languages are often deemed useful because they provide desirable “advanced” 
features. We will see that macros can also deliver most of these features: 


s | e Abstract Data Types: — are user-specified types for data objects, and sets of procedures 
used to access and manipulate them. This “encapsulation” of data items and logic is 
one of the key benefits claimed for object-oriented programming. 


e Information Hiding: — is an established technique for hiding the details of an implemen- 
tation from the user. The concept of separating application logic from data representa- 
© tions is and old and well established programming principle. 
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Examples 
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Private Types: — are user-defined data types for which the implementing procedures are 
hidden. 


Avoiding Side-Effects: — is achieved by having functions only return a value without 
altering either input values or setting of shared variables not declared in the invocation 
of an implementing procedure. 


Polymorphism: allows functions to accept arguments of different types. and enhances 
the possibility of reusing components in many contexts. 


We will see that macros provide simple ways to implement any or all of these features. They 
provide some additional advantages: 


Macros may be written to perform as much or as little as is needed for a particular task. 


Macros can be built incrementally, so that simple functions can be used by more 
complex functions, as they are written. 


New “language” implemented by macros can be adapted to the needs of the applica- 


~ tion, giving an application-specific language that may well be better suited to its needs 


than a-general-purpose “higher level” language designed to (nearly) fit (nearly) every- 
thing. 


We will now examine some sample macros that illustrate various aspects of the macro lan- 
guage. 


We will discuss several sets of example macros that illustrate different aspects of macro 
coding, and which provide various types of useful functions. 


1, 


- The example macros at “Defining Equated Symbols for Registers (Safely)” on page 74 


generate a set of EQU statements to define symbols to be used for register references. 


.They‘illustrate the use of a global variable symbol to set a “one-time” switch, text 


parameterization, use of the &SYSLIST system variable symbol, and created variable 
symbols. | 


Two example macros at “Generating a Byte Sequence” on page 77 generate a 
sequence of byte values. They illustrate conditional assembly statements, and some 
simple string-handling operations. 


The “utility” macros at “Macro-Time Conversion Between Hex and Decimal” on page 79 
might be used by other macros to perform conversions between decimal and 
hexadecimal representations. They illustrate construction of self-defining terms, global 
variables for communicating among macros, and substring operations. 


The example macro at “Generate Lists of Named Integer Constants” on page 81 gener- 


ates a list of constants from a varying-length list of arguments, using &SYSLIST to refer 


to each argument in turn, and constructs a name for each constant using its value. 


The three example macros at “Creating a Prefixed Message Text” on page 83 generate 
a length-prefixed “message” string. The first and second examples illustrate some 
familiar techniques, while the third uses the AREAD statement and a full scan of a 
“human-format” message to generate an insertion-text character string for the final DC 
statement containing the message. 


Three example macros at “Macro Recursion” on page 88 illustrate recursive macro 
calls. The first implements “indirect addressing”, and the remaining two illustrate the 
use of global variable symbols and recursive macro calls to generate factorials and 
Fibonacci numbers. 


Several macros at “Bit Handling” on page 94 illustrate techniques that can be used to 
define a private “bit” data type, with bit addressing by name and type checking within 
the bit handling macros themselves. 
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8. A set of macros illustrated at “Using and Defining Data Types” on page 117 illustrate 
some techniques that can be used to implement type-sensitive operations 
(“polymorphism”), and user-defined data types and user-defined operations on them, 
© with type checking and information hiding. 


Define General Register Equates (Simply) 


« ¢ Easy to do this with a macro like 


MACRO 
GREGS 
GRO EQU 
GRi EQU 
*« 


~% 


GRIS «QU 
MEND 


Problem: what if two code segments are combined, and each calls 
GREGS? 


- How to preserve modularity? 


Answer: use a global variable symbol! 
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Define General Register Equates (Safely) 


© ¢ Use a global variable symbol &GRegs to check for previous calls 


MACRO 
GREGS 
GBLB &GRegs 
AIF (&GRegs) . Done 
LCLA aN 
Xx ANOP 
GREN EQu &N 
aN SETA 8N+1 
AIF (SN LE 15).X 
&GRegs SetB 1 Indicate definitions have been done 
MEXIT 
Bone MNOTE 6, 'GREGS previously called, this call ignored. ' 
MEND 


If &GRegs is true, no statements are generated 


GREGS This,Call,Is, Ignored 


July 1983 High Level Assembler Tutorial Guide 
© Copyright iBM Corporation 1993 


Macro Techniques 73 


Defining Equated Symbols for Registers (Safely) 


The technique illustrated in “Example: Defining Equated Symbols for Registers” on page 47 © 
is quite acceptable unless we need at some point to combine multiple code segments, each 

of which may possible contain a call to GREGS (which was needed for its own modular 

development). How can we avoid generating multiple copies of the EQU statements, with 

their accompanying diagnostics for multiply-defined symbols? 


The solution is simple: use a global variable symbol whose value will indicate that the 
GREGS macro has been called already. This is illustrated in Figure 20 below. : 


MACRO @ 
GREGS 

GBLB &GRegs 

AIF (&GRegs) .Done 

LCLA ~—s @N 

ANOP 

EQU &N 

SETA &N+1 


AIF (&N LE 15).X 

SetB 1 Indicate definitions have been done 

MEXIT 

MNOTE 0, 'GREGS -- Previously called, this call ignored. ' 
MEND 


GREGS What? 
GREGS Again,Eh? 


Figure 20. Macro to Define General Purpose Registers Once Only © 
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Define All Register Equates (Safely) 


¢ Use “created set symbols” for global variable symbol references 


MACRO 
REGS 
General macro to define General, Floating, or Access Registers. 
Just specify the argument A, F, or & for the appropriate set. 
GBLB &GRegs Done, &FRe $s Done »&ARegs_ Done 
AIF (W'asysList eq 8) Ext 
&J SetA Initialize argument counter 
-GetArg ANOP 
aT *SSysList(&J)° Pick up an argument 
('&T' ne 'G' and '&T' ne 'F' and ‘&T' ne 'A').Bad 
(e(ar. Regs_Done)).Done 


&T.RO 

&T.R2 2 

&T.RG 4 

&T.R6 6 
( 
1 
c 


'aT' eq ‘F').Set If type F, only 4 regs to define 
&T.R1 


ontinued -- - 
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Define All Register Equates (Safely) ... 


&T.R3 = EQU 3 

.™ -~-- etc. 

&T.R15 EQU 15 

-Set ANOP 

* &(&T.Regs Done) SetB 1 Indicate definitions have been done 

-Next ANOP 

&J SetA &J+1 Count to next argument 
AIF (&J le N'&SysList).GetArg Get next argument 
MEXIT 

-Bad  MNOTE 8, "REGS — Unknown type ''&T.''.' 
MEXIT 

-Done MNOTE 6,‘REGS — Previously called for type &T..' 
AGO -Next 

-Exit MEND 


If &(&T.Regs_ Done) is true, no statements are generated 


GREGS G 
GREGS 6G,F,A G registers are not defined again 
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Encouraged by the success of this approach, we might wish to define a macro which will 
create equates for a// the registers we might use in our program: General Purpose, Floating 
Point, and Access. Rather than write three separate macros (one for each type of register), 
we can write a single REGS macro whose operands specify the type of registers desired 
(e.g., “G” for GPRs, “F” for FPRs, and “A” for ARs). 


The following example uses the technique illustrated in Figure 20 on page 74 above, but 


generalizes it by using a “created set symbol” to select the name of the proper global vari- 
able symbol. 
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MACRO 
REGS 
General macro to define General, Floating, or Access Registers. 
.* Just specify the argument A, F, or G for the appropriate set. 
GBLB &GRegs_Done,&FRegs Done, &ARegs_ Done 
AIF (N'&SysList eq 0).Exit 


&J SetA 1 Initialize argument counter 
.-GetArg ANOP 
&T SetC '&SysList (&J) ' Pick up an argument 


AIF ('&T' ne 'G' and '&T' ne 'F' and '&T' ne 'A').Bad 
AIF (&(&T.Regs_ Done)).Done 
&T.RO  EQU 0 


&T.R2 EQU 2 
&T.R4 = EQU 4 
&T.R6  EQU 6 
AIF ('&T' eq 'F').Set If type F, only 4 regs to define 
&T.R1  EQU 1 
&T.R3 = EQU 3 
ae -~-- etc. 
&T.R15 EQU 15 
Set ANOP 
&(&T.Regs Done) SetB 1 Indicate definitions have been done 
~Next = ANOP 
&J SetA &J+1 Count to next argument 
AIF (&J le N'&SysList).GetArg Get next argument 
MEXIT 
.Bad MNOTE 8,'REGS -- Unknown type ''&T.'!.' 
MEXIT 
~.Done MNOTE 0,'REGS -- Previously called for type &T..' 
AGO Next 
REGS A 
REGS F,G,A 
~Exit MEND 


Figure 21. Macro to Define Any Sets of Registers Once Only 
This REGS macro may be safely used any number of times (so long as no other definitions 


of the global variable symbols &ARegs Done, &FRegs Done, or &GRegs Done, appear elsewhere in 
the program!)). 
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© Generating a Byte Sequence: BYTESEQ1 Macro 


e BYTESEQ1 generates a byte for each value 


MACRO 
&L BYTESEQ1 &N 
.* BYTESEQ] — generate a sequence of byte values, one Pek statement. 
.* No ae or validation is done. 
&K 


a ("&L' EQ ‘'). Loop Don't define the label if absent 
&L GALI Define the label 
. Loop 
&K &K+1 Increment &K 
(&K GT 8N).Done Check for termination condition 
~ Al1(&K) 
Cont inue 
-Done 


* Two test cases 


BSla BYTESEQ] 5 
BYTESEQ] 1 
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Generating a Byte Sequence: BYTESEQ2 Macro 


MACRO 
BYTESEQ2 &N Generates a single DC statement 
1 . Initialize generated value counter 
ey Initialize output string 
(T'SN EQ 'N').Num Validate type of argument 
8, 'BYTESEQ2 — &8N=8N not self-defining. ‘ 


(8N LE 255) .NotBig Check size of argument 
8, 'BYTESEQ2 —- &8N=8N is too large.’ 


(8N GT 6).0K Check for smal] argument 
*, "BYTESEQ2 — &&N=8N too small, no data generated. ' 


Abe GE &N) .DoDC If done, generate DC statement 
K+1 Increment &K 

ne '.',&K' Add comma and new value of &K to &S$ 

. 0K Cont inue 


AL1(&S) 
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Generating a Byte Sequence 


The sample BYTESEQ2 macro illustrated below in Figure 22 on page 78 uses the same tech- 
niques as the conditional-assembly examples given in Figure 4 on page 2/7 and Figure 5 on 
page 27. and the corresponding BYTESEQ1 macro illustrated in Figure 18 on page 53. 


* The BYTESEQ2 macro shown in Figure 22 on page 78 performs several validations of its 
argument, including a type attribute reference to verify that the argument is a self-defining 
term. As its output, the macro generates a single DC statement for the byte values, but it 
has a curious limitation: can you tell what it is, without reading the text following the next 
figure? 
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MACRO 
&L BYTESEQ2 &N 
.* BYTESEQ2 -- generate a sequence of byte values, one per statement. 
.* The argument is checked and validated, and the entire constant is 
.* generated in a single DC statement. | 


LclA &K 
LelC &S 
&K SetA 1 Initialize generated value counter 
&S SetC ry Initialize output string 
AIF (T'&N EQ 'N').Num Validate type of argument 
MNOTE 8, 'BYTESEQ2 -- &&N=&N not self-defining.' 
MEXIT 
Num = AIF (&N LE 255).NotBig Check size of argument 
MNOTE 8, 'BYTESEQ2 -- &&N=&N is too large.' 
MEXIT 
-NotBig AIF (&N GT 0).0K Check for small argument 
MNOTE *, 'BYTESEQ2 -- &&N=&N too small, no data generated. ' 
MEXIT 
OK AIF (&K GE &N).DoDC If done, generate DC statement 
&K SetA &K+] Increment &K 
&S SetC "8S. '.',&K' =Add comma and new value of &K to &$& 
AGO OK Continue 
-~DoDC  ANOP 
&L DC AL1(&S) 
MEND 


* Test cases 

BS2e BYTESEQ2 0 
BS2b BYTESEQ2 1 
BS2a BYTESEQ2 5 
BS2d BYTESEQ2 X'58! 
BS2c BYTESEQ2 256 


Figure 22. Macro to Define a Sequence of Byte Values As a Single String 


This macro has a problem. Because no character variable symbol may contain more than 
255 characters, the argument to BYTESEQ2 may not exceed 88; otherwise &S exceeds 255 
characters. | 


It is easy to modify the AIF test (at sequence symbol .Num) to enforce an upper limit of 88 for 

' &N. We leave as an exercise to the interested reader what steps could be taken to adapt 
this macro to accept arguments up to and including 255, and still generate a single DC state- 
ment. 
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Macro-Time Conversion from Hex to Decimal 69 


Convert hex digit strings to decimal values in GBLA variable &DEC 


Macro 
Dec &Hex Convert &Hex to decimal 
r GhIA &Dec Decimal value returned in &Dec 


SetC 'X''&Hex''' Create hex self-defining term 

SetA & Do the conversion 

ae 6, '&Hex (hex) = &Dec (decimal)' For debugging 
n 


Dec AA 
*w* MNOTE *** 6,AA (hex) = 176 (decimal) 
Dec FFF 
ex MNOTE *** 6,FFF (hex) = 46095 (decimal) 
Dec FFFFFF 
*** MNOTE *** 6,FFFFFF (hex) = 16777215 (decimal) 
Dec 7FFFFFFF 
“ee MNOTE *** 6, 7FFFFFFF (hex) = 2147483647 (decimal) 
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Macro-Time Conversion from Decimal to Hex 70 


Convert decimal values to hex digit strings in GBLC variable &Hex 


Macro 

Hex &Dec Convert &Dec to hexadecimal 

GbhIC &Hex Hex value returned in &Hex 
© Setc '' Initialize &Hex 

SetA &Dec Local working variable 


ANop , Top of reduction loop 

SetA &Q-&0/16*16 &R = Mod ( &Q, 16 ) 

SetA &Q/16 Quotient for next iteration 

SetC '6123456789ABCDEF'(&R+1,1).'&Hex' Build hex value 
Aif (&Q gt 6).Loop Repeat if &Q not zero 

ve @,'&Dec (decimal) = &Hex (hex)' For debugging 
MEn 


Hex 176 
we* MNOTE *** 6,176 (decimal) = AA (hex) 
Hex 16777215 
we* MNOTE *** 6,16777215 (decimal) = FFFFFF (hex) 
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Macro-Time Conversion Between Hex and Decimal 


lf you are writing macros, it is not uncommon to need from time to time to convert between 
two different representations of a data item. Some of these conversions are already avail- 

> able in the conditional assembly language; for example, arithmetic variables are automat- 
ically converted to character form by substituting them in SETC expressions. 


To illustrate two “utility” macros, we will show how to convert between decimal and 
hexadecimal representations. The first macro, Dec, converts from hex to decimal, and places 
the result of its conversion into the global arithmetic variable &Dec for use by the calling 
macro (or open code statement). Because the assembler accepts hexadecimal self-defining 
terms in SETA expressions, the conversion merely needs to construct such a hexadecimal 
term. 
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Macro 
Dec &Hex Convert &Hex to decimal 
GblA &Dec Decimal value returned in &Dec 


SetC 'X''&Hex!'!! Create hex self-defining term 
SetA &X Do the conversion 

MNote 0, '&Hex (hex) = &Dec (decimal)' For debugging 
MEnd 


Figure 23. Macro-Time Conversion Between Hex and Decimal 


Some examples of calls to the Dec macro are shown in the following figure, where the = 
MNOTE statement has been used to display the results. (In production use, the MNOTE state- 

ment would probably be inactivated by placing a “.*” (conditional-assembly) comment indi- 

cator in the first two columns.) 


AA 
*** @,AA (hex) = 170 (decimal) 
FFF 
*** Q,FFF (hex) = 4095 (decimal) 
FFFFFF 
*** Q,FFFFFF (hex) = 16777215 (decimal) 
7FFFFFFF 
*** Q,7FFFFFFF (hex) = 2147483647 (decimal) 


Figure 24. Macro-Time Conversion Between Hex and Decimal: Examples 


Note that this macro may appear:to have a problem: any hex value exceeding X'7FFFFFFF' ©} 
will not be displayed as a negative number. However, its decimal representation in the vari- 
able &Dec will be correct. 


Conversion from decimal to hexadecimal requires reoneing the decimal value one hex digit 
at a time, using successive divisions by sixteen. 


&Dec Convert &Dec to hexadecimal 
&Hex Hex value returned in &Hex 
a Initialize &Hex 
&Dec Local] working variable 

Top of reduction loop 


3 

&Q-8&Q/16*16 &R = Mod ( &Q, 16 ) 

&Q/16 Quotient for next iteration 
'0123456789ABCDEF' (&R+1,1).'&Hex' Build hex value 
(&Q gt 0).Loop Repeat if &Q not zero 

Q,'&Dec (decimal) = &Hex (hex)' For debugging 


Figure 25. Macro-Time Conversion Between Decimal and Hex 


Some examples of calls to the Hex macro to perform decimal-to-hex conversion are shown in 
the following figure. 
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Hex 170 
*** MNOTE *** 6,170 (decimal) = AA (hex) 
Hex 16777215 
*** MNOTE ***  0,16777215 (decimal) = FFFFFF (hex) 
Hex 16777216 
*** MNOTE *** 0,16777216 (decimal) = 1000000 (hex) 
Hex 2147483647 
*** MNOTE *** 0©,2147483647 (decimal) = 7FFFFFFF (hex) 


Figure 26. Macro-Time Conversion Between Decimal and Hex: Examples 
The technique shown in the Hex macro could be used to convert from decimal to any other 
base, simply by replacing occurrences of the value “16” in the macro with the desired base. 


(As an exercise, rewrite this macro to support a keyword parameter &BASE, with default value 
16, and try it with various bases such as 2, 8, and 12.) 


Generate a List of Named Integer Constants 71 


* Macro to define a list of named integer constants (checking omitted) 


MACRO 

&Lab INTCONS &Type=F 

.TypOK AIF {'&lab' eq '').NoLab Skip if no label 

&Lab oc 6&Type. '6' Define the label 

-ArgsOK ANOP Argument-checking loop 

&J SetA &J+l Increment argument counter 
AIF (&J GT N'&SysList).End Exit if all done 

&Name SetC ‘&lype.&SysList(&J)' Assume non-negative arg 
AIF 


('&SysList(&J)‘(1,1) ne '-').NotNeg Check arg sign 


&Name SetC -'&Type.M'. ‘&SysList(&J)'(2,K'&SysList(&J)-1) Neg Arg 
-NotNeg ANOP 
&Name DC &Type. '&SysList(&J) ' 


AGO .Args0K Repeat for further arguments 
MEND 


INTCONS 6,-1 Type F: names FG, FM1 
INTCONS 99,-99, Type=H Type H: names H99, HM99 
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- Generate Lists of Named Integer Constants 


To illustrate a typical use of the &SYSLIST system variable symbol, we suppose we wish to 
write a macro named INTCONS that will generate integer-valued constants, giving them 
names by appending their value to a letter designating their type (F if the value is non- 
negative, or to FM if the value is negative). For good measure, we will provide a keyword 
parameter to specify their type, either F or H, with F as the default. (Negative halfword con- 
stants will then start with the letters HM.) 
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MACRO 
&Lab INTCONS &Type=F 
<r INTCONS -- assumes a varying number of positional arguments 
ee to be generated as integer constants, with created names. 
se Type will be F (default) or H if specified. 
LclA &d Count of arguments 
LcIC &Name Name of the constant 
ae Validate the Type argument 
AIF ('&Type' eq 'F' OR '&Type' eq 'H').TypOK Check Type 
MNOTE 8,'INTCONS -- Invalid Type=''&Type''.' 
MEXIT 
a Generate the name-field symbol &Lab if provided 
-TypOK AIF ('&Lab' eq '').NoLab Skip if no label 
&Lab DC O&Type. 'Q' Define the label 
Verify that arguments are present; no harm if none. 
-NoLab AIF (N'&SysList gt 0).ArgsOK Check presence of args 
MNOTE *,'INTCONS -- No arguments provided.' 
MEXIT 
.* | Argument-checking loop 
.ArgsOK ANOP | 
&J SetA &J+l1 Increment argument counter 
AIF (&J GT N'&SysList).End Exit if all done 
AIF (K'&SysList(&J) gt 0).DoArg 
MNOTE 4,'INTCONS -- Argument No. &J. is empty.' 
AGO .ArgsOK Go for next argument 
~DoArg ANOP 
&Name SetC '‘&lype.&SysList(&J)' Assume non-negative arg 
AIF .('&Syskist (&J)‘'(1,1) ne '-').NotNeg Check arg sign 
&Name SetC '‘&Type.M'. '&SysList (&J) '(2,K'&SysList(&J)-1) Neg Arg 
-NotNeg ANOP 
&Name DC &Type. '&SysList (&dJ) ' 
AGO .ArgsOK Repeat for further arguments 
-End MEND 


Figure 27. Macro Parameter-Argument Association Example: Create a List of Constants 


Some test cases for the INTCONS macro are shown in the following figure: 


* Test cases -- first has no label, no args; second has no args. 
INTCONS 
INTCONS 
INTCONS 0,-1 


INTCONS 99,-99,Type=H Type H 

INTCONS ~-000000000, 2147483647 

INTCONS 1,2,3,4,Type=D Invalid type 
INTCONS 1,2,3,4,,5,6,7,8,9, 10E/ Null 5th argument 


Figure 28. Macro Example: List-of-Constants Test Cases 


The basic structure of this macro is in two parts: the first (through the second MEXIT state- 
ment, following the MNOTE statement for null arguments) checks the values and validity of the 
arguments, issuing various messages for cases that do not satisfy the constraints of the defi- 
nition. 


The second part (beginning at the sequence symbol .ArgsOK) uses the &SYSLIST system var- 
iable symbol to step through each of the positional arguments in turn, by applying a sub- 
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script (&J) to indicate which positional argument is desired. The argument is checked for 
being non-null, and then to see if its first character is a minus sign. If the minus sign is 

@ present, it is removed for constructing the constant’s name; finally, the constant is generated 
with the required name. 


As an interesting exercise: what would happen if you wished to add a test to verify that each 
argument is a valid self-defining term? Are negative arguments valid? Would the argument 
10E7 be valid? (It’s acceptable as a nominal value in an F-type constant.) 


Create Length-Prefixed Messages 


¢ Create message text prefixed with “effective length” 


MACRO 
&Lab PFMSG1 &Txt 
Fis PFMSG1 — requires that the text of the message, &Txt, 
* contain no embedded apostrophes (quotes) or ampersands. 
LclA &len Effective Length 
SetA K'&Txt Count of text characters 
SetA &Len-3 Deduct 2 for quotes, 1 for effective length 
oc AL1(&Len) , C&Txt 
MEND 


¢ Limited to messages with no quotes or ampersands 


Mla PFMSG1 ‘This is a test of message text 1.' 
Mlb PFMSG1 ‘Hello' 


July 1993 High Level Assembler Tutorial Guide 
© Copyright IBM Corporation 1993 


Creating a Prefixed Message Text 


A common need in many applications is to produce messages. Often, the length of the 
message must be reduced by 1 prior to executing a move instruction, so it is helpful to store 
the message text and its “effective length” (i.e., its true length minus one). 


We will illustrate three macros to create message texts with an effective-length prefix. 
In this first example, the text of the message may not contain any “special” characters, 


‘namely apostrophes (quotes) or ampersands. A Count attribute reference is used to deter- 
mine the number of characters in the message argument. 
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MACRO 
&Lab PFMSG1 &Txt 
* PFMSG1 -- requires that the text of the message, &Ixt, 
contain no embedded apostrophes (quotes) or ampersands. 
LclA &Len Effective Length 
SetA K'&Txt Count of text characters 


SetA &Len-3 Deduct 2 for quotes, 1 for effective length 
DC AL1(&Len) ,C&Txt 
MEND 


PFMSG1 'This is a test of message text 1.' 
PFMSG1 'Hello! 


Figure 29. Macro to Define a Length-Prefixed Message 


Create General Length-Prefixed Messages 


e¢ Allow all characters in message text (pairing may be required) 


MACRO 
&Lab PFMSG2 &Txt 
PFMSG2 — the text of the message, &Txt, may contain embedded 
apostrophes (quotes) or ampersands, so long as they are 
properly patred. The macro expansion generates a symbol 
using the &SYSNDX system variable symbol, and uses a Length 
attribute reference for the effective length. 
icIC = &&T Local variable 
&T SetC '‘TXT&SYSNDX.M' Create symbol to name the text string 
&Lab oc AL1(L'&T.-1) Effective length 
&T oc C&Txt 
MEND 


¢ Quote and ampersand pairs are harder to write, read and translate 


M2a PFMSG2 ‘Test of ‘'This'' && ‘'That''.' 
M2b PFMSG2 ‘Hello' 
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The requirement that no ampersands or quotes may be used in the message text defined by 
PFMSG1 may not be acceptable in some situations. Thus, in Figure 30 on page 85 we will 
define a second macro PFMSG2 that allows such characters in the message, but requires 
that they be properly paired in the argument string. It also generates an ordinary symbol so 
that a length attribute reference may be used. 
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MACRO 
&Lab PFMSG2 &Txt 
PFMSG2 -- the text of the message, &Ilxt, may contain embedded 
apostrophes (quotes) or ampersands, so long as they are 
properly paired. The macro expansion generates a symbol 
using the &SYSNDX system variable symbol, and uses a Length 
attribute reference for the effective length. 


LcIC = &l Local variable — 

SetC 'TXT&SYSNDX.M' Create symbol to name the text string 
DC AL1(L'&T.-1) Effective length 

DC C&Txt 

MEND 


PFMSG2 'Test of ''This'' && ''That''.' 
PFMSG2 ‘Hello’ 


Figure 30. Macro to Define a Length-Prefixed Message With Paired Characters 


One interesting feature of this macro is its use of the &SYSNDX system variable symbol. The 
value of &SYSNDX is incremented by one for every macro call, and the value assigned to a 
given macro macro remains constant throughout its expansion. Thus, &SYSNDX may be 
used to generate symbols that are (much more likely to be) different for every macro expan- 
sion. 


While the PFMSG2 macro defined in this example allows any characters in the message text, 
it is much more difficult to read and understand the macro argument. (Consider, for 
example, how to explain the odd rules about pairing quotes and ampersands to someone 
_who wants to translate the message text into a different language!) 


Create Readable Length-Prefixed Messages | 74 


¢ Allow all characters in message text without pairing, using AREAD 


MACRO 
&Lab PFMSG4 
.* PFMSG4 — the text of the message may contain any characters. 
.* The message is on a single line following the call to PFMSG4. 
LclA = &L,8N Local arithmetic variables 
LclC = &T , &C , 8M Local character variables 
AIF (N'&SYSLIST EQ 6).0K No arguments allowed 
MNote 8, 'PFMSG4 — no operands should be provided. ' 
MEXIT Terminate macro processing 
.0K ANOP 
&N SetA 1 Initialize char-scan pointer to 1 
-* Read the record following the PFMSG4 call into &M 
aM ARead AAV ONCE &£. - (nex stmk of ber macvu cet) 


&H SetC '8M'(1,72) Trim off any sequence field 
&L SetA 72 Point to end of initial text string 
-* Trim off ai blanks from message text 

& 


-Trim AIF ("8M'(&L,1) NE ' ').C Check last character 
al SetA &l-1 Deduct blanks from length 
AGO Trim Repeat trimming loop 
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Create Readable Length-Prefixed Messages ... 


.* Now, apegin scanning the trimmed string for quotes/amper sands 
¢ ('8M'(8N,1) NE '&&'(1,1) AND ‘8M4'(8N,1) NE '''').0 
.* Have ‘found a quote or ampersand 
aT SetC ‘&T'.‘'8M'(8N,1) First copy of doubled character 
ANOP 
SetC ‘&T'.°8M'(8N,1) Second doubled, or normal character 
SetA 8N+1 Increment scan pointer 
AIF (HS LE &L).C Repeat scan to end of message text 
SetA Set to effective length 
oc ALL (BL), C'ar' 


Messages are written as they are expected to appear! 


oe M4a PFMSG4 
Kf Cotest of 'This' & ‘That’. 
M4c PFMSG4 
This is the text of a long message & says nothin’ very much. 
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This limitation can be removed by using an elegant and powerful feature of the macro lan- 
guage, the AREAD statement. 


The AREAD Statement 


The AREAD statement can be used in a macro to read lines from the program into a char- 
acter variable symbol in the macro. If we write 


&CVar AREAD 


then the first statement in the main program following the macro containing the AREAD 
statement (or the macro call that eventually resulted in interpreting the AREAD statement) 
will be “read” by the assembler, and the contents of that record will be assigned to the vari- 
able symbol &CVar. 


We will exploit this capability in the PFMSG4 macro, which reads the text of a message 
written in its desired final form from the line following the macro call. The macro illustrated 
in Figure 31 on page 87 scans the text of the string, creating pairs of quotes and amper- 
sands wherever needed; thus, the writer of the message need not be aware of the peculiar 
rules of the Assembler Language. 
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@ MACRO 
&Lab PFMSG4 


- PFMSG4 -- the text of the message may contain any characters. 


ae The message is on a Single line following the call to PFMSG4, 
— in the form it is expected to take when printed. The macro 
* scans for quotes and ampersands, and creates a pair for each 
* ss of them for the generated constant. The macro includes a test 
“ for the presence of an argument, which should not be present. 
LclA &L,&N Local arithmetic variables 
; LclC =&T, &C, &M Local character variables 
AIF (N'&SYSLIST EQ 0).0K No arguments allowed 
MNote 8,'PFMSG4 -- no operands should be provided.' 
MEXIT Terminate macro processing 
. OK ANOP 
&N SetA 1 Initialize char-scan pointer to 1 
.* -Read‘the record following the PFMSG4 call into &M 
&N ARead 
&M SetC  '&M'(1,72) Trim off any sequence field 
&L SetA 72 Point to end of initial text string 


.* Trim off trailing blanks from message text 
~Trim AIF ('8M'(&L,1) NE ' ').C Check last character 


&L SetA &L-1 Deduct blanks from length 

AGO .Trim Repeat trimming loop 
.* Now, begin scanning the trimmed string for quotes/ampersands 
 @ AIF ('&M'(&N,1) NE '&&'(1,1) AND '&M'(&N,1) NE '''').D 
.* Have found a quote or ampersand 
&T SetC '&T'.'&M'(&N,1) First copy of doubled character 
.D ANOP 
&T SetC '&T'.'&M'(&N,1) Second doubled, or normal character 
&N SetA  &N+l Increment scan pointer 

AIF (&N LE &L).C Repeat scan to end of message text 
&L SetA &L-1 Set to effective length 
&Lab DC AL1(&L),C'&T' 

MEND 


Figure 31. Macro to Define a Length-Prefixed Message With “True Text” 


some test cases for the PFMSG4 macro are shown in the following figure: 


M4a PFMSG4 
Test of 'This' & 'That'. 
M4b PFMSG4 
Hello 
2 M4c PFMSG4 


This is the text of a long message & says nothin' very much. 


. Figure 32. Test Cases for Macro With “True Text” Messages 
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Macro Recursion 


Macros that call themselves either directly or indirectly are recursive. We will first illustrate 
a recursive call with a simple “Load Indirect” macro, which introduces a simple form of indi- 


rect addressing. 


Indirect Addressing via Recursion 


e LI macro calls itself for each level of indirection 


&Lab &Reg, &X Load &Reg with indirection 
('&X'(1,1) eq '*').Ind Branch if indirect 
&Lab L &Reg , &X 
MExit 
-Ind ANop 
&XI SetC '&X'(2,K'&X-1) Strip off leading asterisk 
LI &Reg, &XI Call ourselves recursively 
L &Reg, 6(, &Reg) 
MEnd 


¢ Examples: each asterisk specifies a level of indirection 


LI 3,6(4) Load from 6(4) 
Load from what 6(,4) points to 
Two levels of indirection 
Three levels of indirection 
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Example 1: Indirect Addressing 


In Figure 33 on page 89, the LI macro implements a form of “indirect” addressing: if the 
storage operand is preceded by an asterisk, the assembler interprets this as meaning that 
the operand to be loaded into the register is not at the operand, but is at the address speci- 
fied by the operand without the asterisk.4 Thus, if an instruction was written as 


LI 8, *XXX | Indirect reference via XXX 
then the item to be loaded into R8 is not at XXX, but is at the position “pointed to” by XXX. 
This definition is recursive, in the sense that the “operand” preceded by an asterisk may 


itself be: preceded by an asterisk, which thus provides multiple levels of indirection. A macro 
to implement this form of indirect addressing is shown in Figure 33 on page 89. 


4 Indirect addressing was a popular hardware feature in many second-generation computers, such as 
the IBM 709-7090-7094 series. The hardware supported only a single level of indirect addressing, and 
the instruction syntax was slightly different on those machines: a single asterisk could be appended to 
the mnemonic (as in TRA*), but the operand field was not modified. 
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@ Macro 


LI &Reg, &X Load &Reg with indirection 
Aif ('&X'(1,1) eq '*').Ind Branch if indirect 
L &Reg, &X 
MExit 

: ANop 
SetC '&X'(2,K'&X-1) Strip off leading asterisk 
LI &Reg, &XI Call ourselves recursively 

| L &Reg,0(, &Reg) 
° MEnd 


Figure 33. Recursive Macro to Implement Indirect Addressing 


Some examples of calls to the LI macro are shown in Figure 34, where the “+” characters 
at the left margin are the assembler’s indication of a macro-generated statement. 


Load from 0(4) 


Load from what 0(,4) points to 


Two levels of indirection 


Three levels of indirection 


Figure 34. Recursive Macro to Implement Indirect Addressing: Examples 
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Generate Factorial Values Recursively 


Macro 
&Lab  FACTO1 &N 
.* Factorials def ined by Fac(N) = N * Fac(N-1), Fac(6) = Fac(1) = 6 
GBLA For returning values of inner calls 
AIF ig aN NE 'N').Error WN must be numeric 
&L SetA Convert from external form 
WNote 9, ‘Evaluating FACTO1(&L.)° 
AIF (RL LT 6).Error Can't handle N < 6 
AIF (&L GE 2).Calc Calculate via recursion if N>1 
&Ret Seta 1 F(0) = F(1) = 1 
AGO Test Return to caller 
.Calc ANOP 
&K SetA &L~1 
&Temp SetA &Ret 
FACTOL &K 
&Ret Seta &Ret*&L 
.Test AIF (&SysNest GT 1).Cont 
MNote 6, Factorial (&L.) = &Ret.' 
&lab OC F’&Ret' 
Cont MExit Return to caller 
.Error MNote 11, Invalid Factorial argument 8N..' 
MEnd 
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Example 2: Factorial Function Values 


Probably the best-known recursive function is the Factorial function. It can be defined and 
implemented iteratively (and more simply), but its familiarity makes it useful as an example. 


In the macro in Figure 35 on page 91, the macro FACTO1 uses the global arithmetic variable 
symbol &Ret to return calculated values. 


There are many ways to test for the end of a recursive calculation. In this example, the 


&SYSNEST variable symbol is used to check the “nesting” level at which the macro was 
called. Macros called from open code are at level 1. 
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© Title ‘Factorial Numbers by Macro Recursion' 


Factorial Numbers are defined by 
F(N) = N * F(N-1) 
with F(0) = 1 and F(1) = 1 


. Macro 
FACTO1 &N 
GBLA &Ret For returning values of inner calls 
LCLA &Temp, &K, &l Local variables 
AIF (T'&N NE 'N').Error N must be numeric 
SetA &N Convert from external form 
MNote 0,'Evaluating FACTO1(&L.)' 
AIF (&L LT 0).Error Can't handle N < 0 
AIF (&L GE 2).Calc Calculate via recursion if N> 1 
SetA 1 F(0) = F(1) = 1 
AGO -Test Return to caller 
ANOP 
SetA &L-1 
SetA &Ret 
FACTO1 &K 
SetA &Ret*&i 
AIF (&SysNest GT 1).Cont 
MNote 0,'Factorial (&l.) = &Ret.' 
DC F'&Ret'! 
MExit Return to caller 
-Error MNote 11,'Invalid Factorial argument &N..' 
MEnd 


Figure 35. Macro to Calculate Factorials Recursively 


Some test cases for the FACTO1 macro are shown in the following figure: 


* Test cases 
FACTO] 
FACTO1 
FACTO1 Valid self-defining term 


FACTO Also 

FACTO] 

FACTO] Invalid argument 
FACTO1 Should cause overflow 
End 


Figure 36. Macro to Calculate Factorials Recursively: Examples 


We leave to the reader the modifications needed to allow FACTO1 to be called from other 
. macros. 
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Generate Fibonacci Numbers Recursively 


Macro 
&lLab FIBONACI &N 
.* Fibonacci numbers defined by F(N) = F(N-1)+F(N-2), F(6) = F(1) = 8 
&Ret For returning values of inner calls 
8, Evaluating FIBONACI(8N.), Level &SysNest.' 
(8N LT 6).Error Negative values not allowed 
(8N GE 2).Calc If 8&N > 1, use recursion 
1 Return F(6) or F(1) 
Test Return to caller 
Do computation 
&N-1 First value "K" = N-1 
&N-2 Second value "L" = N-2 
FIBONACI &K Evaluate F(K) = F(N-1) 
SetA &Ret Hold computed value 
FIBONACI &L Evaluate F(L) = F(N-2) 
&Ret+&Temp Evaluate F(N) = F(K) + F(L) 
(&SysNest GT 1).Cont 
8, 'Fibonacci(&N.) = &Ret..' 
F'&Ret' 
-Cont MExit Return to caller 
.Error sah ll, ‘Invalid Fibonacci argument 8&XN..' 
MEn 
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Example 3: Fibonacci Numbers 


The Fibonacci numbers are defined by the recursion relations 


F(N) = F(N—1) + F(N—2) 
with F(®) = 1 and F(1) = 1 


Calculating them recursively is quite inefficient (though educational!) because many values 


are calculated more than once. The global arithmetic variable symbol &Ret is used to return 
values calculated at lower levels of the recursion. | 
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Title ‘Fibonacci Numbers by Macro Recursion' 


Macro 
FIBONACI &N 
GBLA &Ret For returning values of inner calls 
LCLA &Temp, &K, &L Local variables 
MNote 0,'Evaluating FIBONACI(&N.), Level &SysNest. ' 
° AIF (&N LT 0).Error Negative values not allowed 
AIF (&N GE 2).Calc If &N > 1, use recursion 
SETA 1 Return F(Q) or F(1) 
. AGO Test Return to caller 


ANOP Do computation 

SetA &N-1 First value "K" = N-1 
SetA &N-2 Second value "L" = N-2 
FIBONACI &K Evaluate F(K) = F(N-1) 
SetA &Ret Hold computed value 
FIBONACI § &L Evaluate F(L) = F(N-2) 
SetA &Ret+&T emp Evaluate F(N) = F(K) + F(L) 
AIF (&SysNest GT 1).Cont 

MNote 0,'Fibonacci(&N.) = &Ret..' 

DC F'&Ret' 

MExit Return to caller 
MNote 11,'Invalid Fibonacci argument &N..' 
MEnd 


FIBONACI 4 
FIBONACI 5 
End 


Figure 37. Macro to Calculate Fibonacci Numbers Recursively 
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Bit Definition and Manipulation 


* Frequently need to manipulate “bit flags”: 
Set ON, OFF; invert values; test and branch 
e Typical bit-definition statements: 


Flagl DS X Define lst byte of bit flags 
BitA EQU xX'61' Define a bit flag 
Flag2 os X Define 2nd byte of bit flags 
BitB Equ.§ xX‘'1e' Define a bit flag 


Serious defect: no correlation between bit name and byte name! 


Simple technique uses just a single name for all references 


DS X Unnamed byte 
BitA Equ *,X'61' Define BitA: Length Attribute = bit value 
BitB Equ *,X'16' Define BitB: Length Attribute = bit value 
01 BitA,L'BitA Set BitA ON 
NI BitB,255-L'BitB Set BitB OFF 
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Bit Handling 


94 


Applications frequently require status flags with binary values: ON or OFF, YES or NO, 
STARTED or NOT_STARTED, and the like. On a binary machine, such flags are represented 
by individual bits. However,:-few machines provide individually addressable bits; the bits are 
parts of larger data elements such as bytes or words. This means that special programming 
is needed to “address” and manipulate bits by name. 


It is typical in the Assembler Language to define bits using statements like the following: 


Flagl DS X Define Ist byte of bit flags 
BitA EQU X'O1' Define a bit flag 
Flag2 DS X Define 2nd byte of bit flags 
BitB EQU = X'10! Define a bit flag 


and then doing bit operations like 

0] Flag1,BitA Set bit A “on" 
There is implicitly a problem: the names of the bytes holding the flag bits, and the names 
given to the bits, are unrelated. This means that it is easy to make mistakes like the fol- 
lowing: 


01 Flagi,BitB Set Bit B "on" ?? 
™ Flag2,BitA Test Bit A ?? 


When there is no strict association between the byte and the bit it “contains”, there is no 
way for the assembler (and often, the programmer) to detect such misuses. 


One solution to the “association” problem is to use length attribute references to designate 
bit values. This allows us to “name” a bit, as follows: 
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-NoNamel DS X 


BitA EQU = *,X'O1' Length Attribute = bit value 
~NoName2 DS X 
BitB EQU = *,X'10! Length Attribute = bit value 


That is, the bit name is the same as the name of the byte that contains it. Then, all bit refer- 
ences are made only with the bit “names”: 


. 01 BitA,L'BitA Set Bit A "on" 
™ BitB,L'BitB Test Bit B 


and (if one is careful) the bits will never be associated with the wrong byte! There is, of 
course, no guarantee that one might not write something like 


OI BitA,L'BitB 22? 


- but a quick scan of the symbol cross-reference will show that there are unpaired references 
‘to the symbols BitA and BitB in this statement; correct references will occur in pairs. 


Simple Bit-Handling Macros: Defining Bit Flags 


Macro , Error checking omitted 
BitDefi 
128,64,32,16,8,4,2,1 Define bit position values 
N'&SysList Number of bit names provided 
Name counter 
(8M gt &NN) .Done Check if names exhausted 
1 Start new byte at leftmost bit 
B'6' Allocate a bit-flag byte 
. , Get a new bit name 
"&SysList (8M) ' Get M-th name from argument list 
7 *, &L(&C) Define bit via length attribute 
Step to next name 


&Hi+1 

(8M gt &NN).Done Exit if names exhausted 

&C+1 Count bits in a byte 

(&C le 8) .NewN Get new name if not done 

NB Byte is filled, start a new byte 


BitDefl b1,b2,b3,b4,b5,b6,b7,b8 Eight bits in one byte 
BitDefl c,d,e,f,g,h,1,j,k,1,m,n,0,p,qg,r,s,t,u,v Many bitstbytes 
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Bit-Handling Macros: Simple Forms 


The simplest way to “encourage” correct matching of bit names and byte names is to make 
bit references with macros. Thus, we will illustrate a simple set of macros to do this. 


First, suppose we want to “define” bit names. We will write a macro that accepts a list of bit 
names, and defines bit values in successive bytes, eight bits to a byte. The BitDefl macro in 
Figure 38 on page 96 takes the names in the argument list and allocates a single bit to 

' each, eight bits to a byte. Each call to BitDefl starts a new byte. 
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Macro 
BitDefl 
128,64,32,16,8,4,2,1 Define bit position values 
N'&SysList Number of bit names provided 
1 Name counter 
(& gt &NN).Done Check if names exhausted 
1 Start new byte at leftmost bit 
B'Q! Allocate a bit-flag byte 
‘ Get a new bit name 
"&SysList (&M) ! Get M-th name from argument list 
('&B' eq '').Nul] Note null argument 
*,&L(&C) Define bit via length attribute 
&M+1 Step to next name 
(& gt &NN).Done Exit if names exhausted 
&C+] Count bits in a byte 
(&C le 8).NewN Get new name if not done 
~NB Byte is filled, start a new byte 
MNote 4,'BitDefl: Missing name at arglist position &M' 
SetA &M+1 Step to next name 
Aif  (&M le &NN).NewN Go get new name if not done 
MEnd 


Figure 38. Bit-Handling Macros: Simple Bit Definition 


some examples of calls to the BitDefl macro are shown in the following figure: 


BitDefl b1,b2,b3,b4,b5,b6,b7,b8 Eight bits in one byte 


BitDefl c,d,e,f,g,h,i,j,k,1,m,n,0,p,q,r,S,t,u,v Many bitst+bytes 
BitDefl 
BitDefl F1,,F3 Omitted name 


Figure 39. Bit-Handling Macros: Example of Bit Definitions 


This simple macro has several limitations: 


e Bits cannot be “grouped” so that related bits are certain to reside in the same byte, 
except by writing a statement with a new BitDefl call. 


e This means that we cannot plan to use the bit-manipulation instructions (which can 
~* handle up to 8 bits simultaneously) without manually arranging the assignments of bits 
and bytes. 


We will explore some techniques that can be used to overcome these limitations in “Bit- 
Handling Macros: Advanced Forms” on page 102. 
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Simple Bit-Handling Macros: Setting Bits ON 


° Macro Bit0nl to set one or more bits ON 


Macro , Error Checking omitted 
N'&SysList Number of Names 


1 

('&lLab' eq '').Next Skip if no name field 
6H'6' Define label 

’ Get a bit name 
*BSysList (8M) ° Extract name 

&B,L'&B Set bit on 

&M+1 Step to next bit name 
(8 le &NN) .Next Go get another name 


BitOnl b1,b3,b8,c,d Set various bits ON 
BitOnl b5,b6 Set two more bits ON 
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Simple Bit-Manipulation Macros 


Having defined some bits with this BitDef1 macro, we will write some macros to manipulate 
them by setting them on and off, and by inverting (“flipping”) their state. First, we will write a 
macro BitOn1 that will set a bit to an “on” state (i.e., to 1). 


Macro 

BitOnl 

SetA N'&SysList Number of Names 

SetA 1 

Aif  (&NN gt 0).0K Should not have empty name list 
MNote 4,'BitOnl: No bit names?! 

MExit | 

ANop , Names exist in the list 
Aif ('&Lab' eq '').Next Skip if no name field 

DC QH'Q' Define label 

ANop , Get a bit name 

SetC '&SysList(&M)' Extract name 

Aif ('&B' ne '').Go Check for missing argument 
MNote 4,'BitQnl: Missing argument at position &M' 

Ago  .Step Go look for more names 

0] &B,L'&B Set bit on 

ANop , 

SetA &M+1 Step to next bit name 

Aif  (&M Te &NN).Next Go get another name 

MEnd 


Figure 40. Bit-Handling Macros: Simple Bit Setting 


In the following figure, we illustrate some calls to this macro to perform various bit settings; 
the generated statements are flagged with a “+” in the left margin: 
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BitOnl b1,b3,b8,cl1,c2 

DC OH'0' Define label 
O] b1,L'bl Set bit on 
OI b3,L'b3 Set bit 

0] b8,L'b8& Set bit 


0] else] Set bit 
0! c2,L'c2 Set bit 


BitOnl b1,b8 
0] b1,L'bl Set bit 
0] b8,L'b8 Set bit on 


Figure 41. Bit-Handling Macros: Examples of Bit Setting 


Each bit operation is performed by a separate instruction, even when two or more bits have 
- been allocated in the same byte. We will see in “Bit-Handling Macros: Advanced Forms” on 
page 102 how we might remedy this defect. 


Simple Bit-Handling Macros: Set OFF and Invert Bits 


¢ Macros BitO0ffl and BitInv are defined just like BitOnl: 


Macro 
&lab Bitoffl 
Pi) --- etc., as for Bit0nl 
.Go NI &B,255-L'&B Set bit off 
Ph a SS “Ole, 
MEnd 


Macro 

BitInvl 

--- etc., as for Bit0nl 

XI &B,L'&B Invert bit 
as Se etc. 

MEnd 


BitOffl b1,b3,b8,c,d Set various bits of 
BitOffl  b5,b6 Set other bits off 
BitInvl] b1,b3,b8,c,d Invert various bits 
BitInvl  b5,b6 Invert other bits 
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The BitOffi macro is exactly like the BitOn1 macro, except that the generated statement to 
set the bit “off” (i.e., to 0) is changed: 


Macro 
BitOffl 
- -- etc., as for BitOnl 


NI &B,255-L'&B Set bit off 
- -- etc., as for BitOnl 
MEnd 


Figure 42. Bit-Handling Macros: Simple Bit Resetting 


Some macro calls that illustrate the operation of the BitOff1 macro are shown in the fol- 
lowing figure: 
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: BitOffl b1,b3,b8,cl,c2 
DC OH'0' Define label 


NI _b1,255-L'bl Set bit off 
NI _b3,255-L'b3 Set bit off 
NI b8,255-L'b8 Set bit off 
NI ¢1,255-L'cl Set bit off 
NI ¢2,255-L'c2 Set bit off 
BitOffl b1,b8 
NI b1,255-L'b1 Set bit off 

: NI b8,255-L'b8 Set bi 


Figure 43. Bit-Handling Macros: Examples of Bit Resetting 


Similarly, the Bitlinv1 macro inverts the designated bits: 


Macro 
BitInvl 
--- etc., as for Bit0nl 


XI &B,L'&B Invert bit 
--- etc., as for BitOnl 
MEnd 


Figure 44. Bit-Handling Macros: Simple Bit Inversion 


@ Some calls to BitInv1 illustrate its operation: 


BitInvl b1,b3,b8,cl,c2 

DC QH'O! Define 
XI b1,L'bl Invert 
X] b3,L'b3 Invert 
XI b8,L'b8 Invert 


XI cl,L'cl Invert 
X] c2,L'c2 Invert 


BitInvl b1,b8 
XI b1l,L'bl Invert 
XI b8,L'b8 Invert 


Figure 45. Bit-Handling Macros: Examples of Bit Inversion 
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Simple Bit-Handling Macros: Branch on Bit Values 


¢ Simple bit-testing macros: branch to label L if bit B is on/off 


Macro 
&lLab BitBOnl &B8,&T Bitname and branch label 
&lLab ™ &B, L'&B Test specified bit 

BO &T Branch if ON 

MEnd 


Macro 

BitBOffl &B,&T Bitname and branch label 
Test specified bit 
Branch if OFF 


BitBOnl  b2,bb1 Branch to bbl if b2 is on 
BitBOffl b3,ddl Branch to ddl if b3 is off 
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To complete our set of simple bit-handling macros, suppose we need macros to test the 
setting of a bit, and to branch to a designated label if the bit is on or off. We can write two 
macros named BitBOn1 and BitBOff1 to do this; each has two arguments, a bit name and a 
label name. 


Macro 
~BitBOn1 &B,&T | Bitname and branch label 
Aif  (N'&SysList eq 2).0K Should have exactly 2 arguments 
MNote 4,'BitBOnl: Incorrect argument list?' 
MExit 
Aif ('&8' eq '' or '&T' eq '').Bad 
TM &B,L'&B Test specified bit 
BO &T Branch if ON 
MExit 
MNote 8,'BitBonl: Bit Name or Target Name missing' 
MEnd 


Figure 46. Bit-Handling Macros: Branch if Bit is On 


Some examples of.calls to the BitBOn1 macro are shown in the following figure: 


BitBOnl bl,aal 
™M b1,L'bl Test specified bit 
BO aal Branch if ON 


BitBOnl b2,bbl 
T™M b2,L'b2 Test specified bit 
BO bbl Branch if ON 


Figure 47. Bit-Handling Macros: Examples of “Branch if Bit On” 


A similar. macro can be written to branch to a specified label if a bit is off: 
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Macro 
BitBOffl &B,&T Bitname and branch label 
2+ etc., as for BitBOnl macro 


T™ &B,L'&B Test specified bit 
BNO &T Branch if OFF 
--- etc., as for BitBOnl macro 

MEnd 


Figure 48. Bit-Handling Macros: Branch if Bit is Off 


Calls to the BitBOf1 macro might appear as follows: 


BitBOffl bi,ddl Branch to ddl if bl is off 
T™ b1,L'bl Test specified bit 
BNO ddl Branch if OFF 


BitBOffl b2,ddl Branch to ddl if b2 is off 
™ b2,L'b2 Test specified bit 
BNO ddl Branch if OFF 


Figure 49. Bit-Handling Macros: Examples of “Branch if Bit Off” 


This completes our first set of bit-handling macros. It is evident that a fairly helpful set of 
capabilities can be written with a very small effort, and be put into immediate use. 
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Bit-Handling Macros: Enhancements 


¢ The previous macros work, and can be put to immediate use 
* They can be enhanced in two ways: 
1. Check to ensure that “bit names” really do name bits! 


. Bad Code — 
Flag Equ X'68' Define a flag bit "somewhere" 


BitOnl Flag Set "something, somewhere" 777 


: ) 
-> Let’s use “strong typing!” ts Flas really a/ Lt ' 


2. Permit bits within one byte to be “handled” with one instruction 


~ Let’s do code optimization! 
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Bit-Handling Macros: Advanced Forms 


There are two problems with the preceding “simple set” of bit-handling macros: 


1. it is common to want to operate on more than one bit within a given byte at the same 
time. For example, suppose two bits are defined within the same byte: 


DS X 
BitdJ EQU = *,X'40' 
BitK EQU = *,X'20! 


We would prefer to set both bits “on” with a single Ol instruction. Two possibilities are 
evident: 


01 BitJ,L'Bitd+L'BitK 
01 BitK,L'BitJ+L'BitkK 


Unfortunately, both of these schemes do not satisfy our intent to name just the bits we 
-wish to manipulate, and not the bytes in which they are defined. Thus, we need some 
degree of “optimization” in our bit-handling macros. 


2. There is no checking of the “bit names” presented as arguments in the bit-manipulation 
macros to verify that they were indeed declared as bits in a “bit definition” macro. For 
example, one might have written (through some oversight, probably not as drastic as 
this!) 

Flag Equ X'08' Define a flag bit 


BitOnl Flag Set "something, somewhere" on ??? 


and the result would not have been what was expected or desired. Thus, we need 
some degree of “strong typing” and “type checking” in our bit-handling macros. 


We will start with a BitDef macro that declares bit flags, and keeps track of which ones have 
been declared. We will add an extra feature: if a group of bits should be kept in a single 


102 High Level Assembler Tutorial Guide 


byte, their names may be specified as a parenthesized operand sublist, and the macro will 
ensure that (if at most eight are Specified) they will fit in a byte. Thus, in 


es fea 
BitDef a,b,c, (d,e f,g,h sijsdek 


the bits named a,b,c will be allocated in one byte, and bits d,e,f,g,h,i will be allocated in a 
new byte because there is not enough room left for all of them in the byte containing a,b,c. 
However, bits j,k will share the same byte as d,e,f,g,h,i because there are two bits 
remaining for them. 


One of the decisions influencing the design of these macros is that we wish to optimize exe- 
cution performance more than we wish to minimize storage utilization; because bits are 
small, wasting a few shouldn’t be a major concern. 


Bit-Handling Macros: Bit Definition 


Macro , Some error checks omitted 
BitDef 
GhIA &BitDef ByteNo Used to count defined bytes 
SetA 128,64,32,16,8,4,2,1 Define bit position values 
SetA N' &SysList Number of bit names provided 
Seta 1 Name counter 
Aif Nat gt 8&NN).Done Check if names exhausted 
sets Start new byte at leftmost bit 
es Define a bit-flag byte 
&Bitdef Bytete SetA &BitDef_ByteNo+l Increment byte number 
.NewN — ANop Get a new bit name 
SetC ‘sSysList(8M)' Get M-th name from argument list 
"&B'(1,1) ne '(').NoL Branch {f not a sublist 
SetA N'&SysList (8M) Number of sublist elements 
Initialize count of sublist items 
(&C+8NS Te 9).SubT Skip if room left in current byte 
1 Start a new byte 
C B'6' Define a hit-flag byte 
| eee _ByteNo SetA &BitDef ay enone Increment byte number 
(cont inued) 
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Bit-Handling Macros: Bit Definition ... 


-SubT ANop , Generate sublist equates 
&B SetC ‘&SysList(8M,&Cs) ' Extract sublist element 
GhIA &(BitDef_&B. ByteNo) Declare byte number for this bit 
&B EQU  *,&L(&C) Define bit via length attribute 
eieties a8. _ByteNo) SetA &BitDef_ByteNo Byte no. for this bit 
SetA &CS+1 Step to next sublist item 
Aif (&CS gt &NS).NewA Skip if end of sublist 
ac SetA &C+1 Count bits in a byte 
Ago’ .Subt And go do more list elements 
-NoL ANop Not a list 
GbIA &(Bitdef_ &B. ByteNo) Declare byte number for this bit 
EQU = *, &L(&C) Define bit via length attribute 
a(sitbef &B. _ByteNo) SetA &BitDef_ByteNo Byte no. for this bit. 
.NewA op , Ready for next argument 
SetA &H+] Step to next name 
Aif (8 gt &NN).Done Exit if names exhausted 
SetA &C+1 Count bits in a byte 
Aif (&C le 8).NewN Get new name if not done 
Bit filled, start a new byte 
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Declaring Bit Names 


In the BitDef macro illustrated in Figure 50, several techniques are used. The global arith- 
metic variable &BitDef ByteNo is used to keep track of a “byte number” in which the various 
bits are allocated; each time a new byte is allocated, this variable is incremented by 1. The 
first SETA statement initializes the local arithmetic array variables &L(1) through &L(8) to 
values corresponding to the binary weights of the bits in a byte, in left-to-right order. 


After each bit name has been extracted from the argument list, a global arithmetic variable 
&(BitDef_&B. ByteNo) is constructed (and declared) using the supplied bit name as the value 
of &B, and is assigned the value of the byte number to which that bit will be assigned. This 
has two effects: 


1. a unique global variable symbol is generated for every bit name; 


2. the value of that symbol identifies the byte it “belongs to” (remember that the bytes 
have no names themselves; references in actual instructions will be made using bit 
names and length attribute references). 


An additional benefit of this technique is that later references to a bit can be checked 
against this global variable: if its value is zero (meaning it was declared but not initialized) 
we will Know that the bit was not declared, and therefore not allocated to a byte in storage. 


The other new feature introduced in this macro definition is the ability to handle sublists of 
_ bit names that are to be allocated within the same byte. 


Macro 
BitDef 
GbIA &BitDef_ByteNo Used to count defined bytes 
&L(1) «= SetA 128,64,32,16,8,4,2,1 Define bit position values 
&NN SetA N'&SysList Number of bit names provided 
&M SetA 1 Name counter 
NB Aif (8M gt &NN).Done Check if names exhausted 
&C SetA 1 Start new byte at leftmost bit 
DC B'Q' Define a bit-flag byte 
&BitDef ByteNo SetA &BitDef_ByteNo+1l Increment byte number 
-NewN ANop , Get a new bit name 
&B SetC '&SysList (8M) ' Get M-th name from argument list 
Aif  ('&B' eq '').Null Note null argument 
Aif  ('&B'(1,1) ne '(').NoL Branch if not a sublist 
&NS SetA N'&SysList (&M) Number of sublist elements 
Aif  (&NS gt 8).Errs Error if more than 8 


Figure 50 (Part 1 of 2). Bit-Handling Macros: Define Bit Names 
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&Ccs SetA 1 Initialize count of sublist items 
Aif (&C+&NS le 9).SubT Skip if room left in current byte 


&C SetA 1 Start a new byte 

DC B'Q! Define a bit-flag byte 
&BitDef_ByteNo SetA &BitDef ByteNo+] Increment byte number 
-SubT ANop , Generate sublist equates 
&B SetC ‘&SysList(&M,&CS) ' Extract sublist element 


GbIA &(BitDef_&B. ByteNo) Declare byte number for this bit 
Aif (&(BitDef_&B. ByteNo) gt 0).DupDef Branch if declared 


&B EQU = *,&L(&C) Define bit via length attribute 
. &(BitDef_&B. ByteNo) SetA &BitDef ByteNo Byte no. for this bit 
&CS SetA &CS+l | Step to next sublist item 
Aif (&CS gt &NS).NewA Skip if end of sublist 
&C SetA &C+1 Count bits in a byte 
Ago’ .Subt And go do more list elements 
-NoL ANop Not a list 


9 
Gb1A &(BitDef &B. ByteNo) Declare byte number for this bit 
Aif (&(BitDef_&B. ByteNo) gt 0).DupDef Branch if declared 


&B EQU*, &L(&C) Define bit via length attribute 
&(BitDef_&B. ByteNo) SetA &BitDef_ByteNo Byte no. for this bit 
-NewA ANop , Ready for next argument 
&M SetA &M+1 Step to next name 
Aif (8M gt &NN).Done Exit if names exhausted 
&C SetA &(+1 Count bits in a byte 
Aif  (&C le 8).NewN Get new name if not done 
Ago’ .NB Bit filled, start a new byte 
-DupDef MNote 8,'BitDef: Bit name ''&B'' was previously declared. ' 
MExit 
-ErrS MNote 8,'BitDef: Sublist Group has more than 8 members' 
MExit 
-Null MNote 8,'BitDef: Missing name at argument &M' 
-Done MEnd 


Figure 50 (Part 2 of 2). Bit-Handling Macros: Define Bit Names 


Some examples of calls to this BitDef macro are shown in the following figure; the gener- 
ated instructions are displayed (with “+” characters in the left margin) for two of the calls: 
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a4 BitDef di1,d2,d3, (d4,d5,d6,d7,d8,d9) ,d10 d4 starts new byte 
+ DC B'Q! Define a bit-flag byte 
+d] EQU = *,128 Define bit via length attribute 
+d2 EQU  =*,64 Define bit via length attribute 
+d3 EQU *,32 Define bit via length attribute 
+ DC B'Q' Define a bit-flag byte 
+d4 EQU  *,128 Define bit via length attribute 
+d5 EQU  *,64 Define bit via length attribute 
+d6 EQU » 32 Define bit via length attribute 
+d7 EQU , 16 Define bit via length attribute 
+d8 EQU *,8 Define bit via length attribute 
+d9 EQU *,4 Define bit via length attribute 
+d10 EQU *,2 Define bit via length attribute 
a5 BitDef el,e2,e3,e4,e5,e6,e7, (e8,e9) e8 starts new byte 
a6 BitDef g1,(92,93,94,95,96,97,98,99) g2 starts new byte 
a7 BitDef (h2,h3,h4,h5,h6,h7,h8,h9,h10),h11 error, 9 in a byte 
a9 BitDef (k1,k2,k3,k4), (k5,k6,k7,k8),k9,k10 two sublists 
+ DC B'Q' Define a bit-flag byte 
+kl EQU = *,128 Define bit via length attribute 
+k2 EQU *,64 Define bit via length attribute 
+k3 EQU = *,32 Define bit via length attribute 
+k4 EQU *,16 Define bit via length attribute 
+k5 EQU *,8 Define bit via length attribute 
+k6 EQU *,4 Define bit via length attribute 
+k7 EQU *,2 Define bit via length attribute 
+k8 EQU:  * 1 Define bit via length attribute 
+ DC B'Q' Define a bit-flag byte 
+k9 EQU = *,128 Define bit via length attribute 
+k10 EQU  *,64 Define bit via length attribute 
ald BitDef 11,(12,13,14),(15,16,17,18),19,110 two sublists 
all BitDef m1, (m2,m3,m4),(m5,m6,m7,m8,m9),m10 two sublists 


Figure 51. Bit-Handling Macros: Examples of Defining Bit Names 


We will now see how we can utilize the information created by this BitDef macro to gen- 
erate efficient instruction sequences to manipulate them. 
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_ Bit-Handling Macros: Set Bits ON 


Macro Bit0n optimizes generated instructions (most error checks 


omitted) 

Macro 
: BitOn 

SetC ‘&Lab' Save label 

SetA 6 No. of distinct Byte Nos. 

SetA 6 Name counter 

SetA N'&SysList Number of names provided 

Atf (8M ge &NN).Pass2 Check if all names scanned 
: au SetA &+1 Step to next name 


SetC ‘&SysList (8M) ' Pick off a name 

GhIA &(BitDef_&B. ByteNo) Declare GBLA with Byte No. 
Aif (&(BitDef_&B. ByteNo) eq @).UnDef Exit if undefined 
SetA 86 Loop through known Byte Nos 
Aif  (&K ge 8&NBN) .NewBN Not in list, a new Byte No 
SetA &K+1 Search next known Byte No 
Aif (&BN(&K) ne &(BitDef_&B. ByteNo)).BNLp Check match 
--- continued 
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Bit-Handling Macros: Set Bits ON ... 


&J SetA 1 Check if name already specified 
-CkDup Aif (&) gt SIBN(&K)).NmOK Branch if name is unique 
Aif (‘&B' eq '&(BitDef_Nm_&BN(&K). &J)').DupNm Duplicated 
&J SetA &J+1 Search next name in this byte 
Ago .CkDup Check further for duplicates 
. DupNm ere 8, 'BitOn: Name ''&B'' duplicated in operand list‘ 
MExit 
-NmOK ANop , No match, enter name in list 
&IBN(&K) SetA &IBN(&K)+1 Have matching BN, count up by 1 
Lc1C &(BitDef Nm &BN(&K). &IBN(&K) ) Slot for bit name 
&(BitDef_Nm_&BN(&K). &IBN(&K)) SetC '&B' Save K'th Bit Name, this byte 
Ago .NMLp Go get next name 
-NewBN ANop , New Byte No 
&NBN SetA S&NBN+1 Increment Byte No count 
&BN(&NBN) SetA &(BitDef_&8. ByteNo) Save new Byte No 
&IBN(&NBN) SetA 1 Set count of this Byte No to 1 
LclC &(BitDef_Nm &BN(&NBN). 1) Slot for first bit name 
&(BitDef_Nm &BN(8NBN). 1) SetC '&88' ~ Save Ist Bit Name, this byte 
Ago .NMLp Go get next name 
--- continued 
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Bit-Handling Macros: Set Bits ON 


ANop , Pass 2: scan Byte No list é 


SetA 6 Byte No counter 

Aif (84 ge 8NBN) .Done Check if all Byte Nos done 

SetA &M+1 Increment outer-loop counter 

SetA &BN(&M) Get M-th Byte No 

SetA 1 Set up inner loop 

SetC '&(BitDef Nm &X. &K).,L''&(BitDef_Nm_&X. &K)' Operand 

Aif a ge RIBN (3M) )~ GenOl een Toop, check for done 

SetA &K+ to next bit in this byte e 

SetC Bop +L''&(BitDef_Nm_&X. “ik Add next bit to operand 

Ago .OpLp Loop (inner) for next operand 

ANop , Generate instruction for Byte No 

oI &Op Turn bits ON 

Setc '' Nullify label string 
Loop (outer) for next Byte No ‘ 


Ago’ .BLp 

MNote 8,'BitOn: Name ''&B’' not defined by BitDef' 
MExit 

MEnd 
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Using Declared Bit Names in a BitOn Macro 


The BitOn macro accepts a list of bit names, and generates the minimum number of 
instructions needed to set them on (i.e., to 1), as illustrated in Figure 52 on page 109. The 
macro makes two “passes” over the supplied bit names: 


&(BitDef_&B. &ByteNo) (where the value of &B is the bit name) is constructed and 
declared, and its value is checked. If the value is zero, we know that the name was not 
declared in a call to a BitDef macro (which would have assigned a non-zero byte 
number value to the variable). 


e In the first pass, the bit names are read, and the global arithmetic variable @ 


e Ifthe bit name was defined, the value of the constructed name is the byte number of the 
byte to which the bit was assigned. The array &BN() is searched to see if other bits with 
the same byte number have been supplied as arguments to this BitOn macro; if not, a 
new entry is made in the &BN() array. 


e A-second array &IBN() (paralleling the &BN() array) is used to count the number of 
Instances of the Byte Number that have occurred thus far. 


e Finally, the bit name is saved in a created local character variable symbol 

—. &(BitDef_Nm_&bn. &in), where &bn is the byte number for this bit name, and &in is the 
“instance number” of this bit within this byte. (By checking the current bit name from 
the argument list against these names, the macro can also determine that a bit name 
has been “duplicated” in the argument list.) 


Once all the names in the argument list have been handled, the macro uses the information 
in the two arrays and the created local character variable symbols: 


e In the second pass, one instruction will be generated for each distinct byte number that 
was entered in the &BN() array during the first pass, using two nested loops; the outer 
loop is executed once per byte number. 


e The inner loop is executed as many times as there are instances of names belonging to 
the current byte number (as determined from the elements of the &IBN() array), and con- 
structs the operand field in the local character variable &0p, using the created local char- 
acter variable symbols to retrieve the names of the bits. a 
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At the end of the inner loop, the Ol instruction is generated using the created operand 


field string in &0p, and then the outer loop is repeated until the instructions for all the 
bytes containing named bit have been generated. 


Macro 
&Lab BitOn 
&L SetC '&Lab' 
&NBN SetA 0 
&M SetA 0 
&NN SetA N'&SysList 
~NmLp  Aif (8&8 ge &NN).Pass2 
&M SetA &M+1 
&B SetC '‘&SysList (&M) ' 


GbIA &(BitDef_&B. ByteNo) 


Save label 

No. of distinct Byte Nos. 
Name counter 

Number of names provided 
Check if all names scanned 
Step to next name 

Pick off a name 

Declare GBLA with Byte No. 


Aif (&(BitDef_&B. ByteNo) eq 0).UnDef Exit if undefined 


Loop through known Byte Nos 
Not in list, a new Byte No 
Search next known Byte No 


Aif en ne &(BitDef_&B. ByteNo)).BNLp Check match 


Check if name already specified 
Branch if name is unique 


Aif ('&B' eq '&(BitDef_Nm_&BN(&K). &J)').DupNm Duplicated 


Search next name in this byte 
Check further for duplicates 


-DupNm MNote 8,'BitOn: Name ''&B'' duplicated in operand list' 


&K SetA 0 
-BNLp Aif (&K ge &NBN) .NewBN 
&K SetA &K+1 
&J SetA 
-CkDup Aif mn gt &IBN(&K)).NmOK 
&J SetA &J+l 
Ago .CkDup 
MExit 
. NmOK ANop , 


RIBN(&K) SetA &IBN(&K)+1 


LclC &(BitDef_Nm_ &BN(&K). &IBN(&K)) 


No match, enter name in list 
Have matching BN, count up by 1 
Slot for bit name 


&(BitDef_Nm_&BN(&K). &IBN(&K)) SetC '&B' Save K'th Bit Name, this byte 


Ago  .NMLp 
-NewBN ANop , 
&NBN SetA &NBN+1 
&BN(&NBN) SetA &(BitDef_&B. ByteNo) 
&IBN(&NBN) SetA 1 


LclC &(BitDef_Nm &BN(&NBN). 


&(BitDef_Nm &BN(&NBN). 1) SetC '8B! 


Go get next name 

New Byte No 

Increment Byte No count 

Save new Byte No 

Set count of this Byte No to 1 


_1) Slot for first bit name 


Save Ist Bit Name, this byte 


| Ago  .NMLp Go get next name 
-Pass2 ANop , Pass 2: scan Byte No list 
&M SetA 0 Byte No counter 
-BLp Aif (& ge &NBN).Done Check if all Byte Nos done 
&M SetA &M+1 Increment outer-loop counter 
&X SetA &BN(&M) Get M-th Byte No 
&K SetA 1 Set up inner loop 
&0p SetC '&(BitDef_Nm &X. &K).,L''&(BitDef_Nm &X. &K)' Operand 
.OpLp Aif  (&K ge &IBN(&M)).Gen0I Operand loop, check for done 
&K SetA &K+l Step to next bit in this byte 
&0p SetC '&Op.+L''&(BitDef_Nm_&X. &K)' Add next bit to operand 

Ago’ .0OpLp Loop (inner) for next operand 


Figure 52 (Part 1 of 2). Bit-Handling Macros: Set Bits ON 
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Generate instruction for Byte No 
Turn bits ON 
Nullify label string 


Loop (outer) for next Byte No 
8,'BitOn: Name ''&B'' not defined by BitDef' 


Figure 52 (Part 2 of 2). Bit-Handling Macros: Set Bits ON 


Some examples of calls to the BitOn macro are illustrated in the figure below. In each case, 
the minimum number of instructions necessary to set the specified bits will be generated. 
The instructions generated by the macro are shown for two of the calls. 


— BitOn b1,b2 
0] b1,L'b1+L'b2 Turn bits ON 


BitOn bl,c2,bl Duplicate bit name 'bl' 
BitOn jj Undeclared bit name 'jj' 
BitOn cl,c2,c3,c4,c5,c6,c7,c8,c9,cl0,cl1,c12,c13,c14,c15,cl6,c17 


Fbg BitOn bl,cl,di,el,b2,c2,d2,c3,b3,m2,c4,c5,m5,d6,c6,d7,b4,c7 

+Fbg b1l,L'b1+L'b2+L'b3+L'b4 Turn bits ON 
cl,L'cl+L'c2+L'c3+L'c4+L'cdot+L'c6+L'c7 Turn bits ON 

d1,L'd1+L'd2 Turn bits ON 

el,L'el Turn bits ON 

m2,L'm2 Turn bits ON 

m5,L'm5 Turn bits ON 

d6,L'd6+L'd7 Turn bits ON 


BitOn bl,c2,c3,c4,c5,c6,c7,c8,c9,c10,b1 Duplicated name 'bl' 


Figure 53. Bit-Handling Macros: Examples of Setting Bits ON 
Extending this macro to create BitOff and BitInv macros is straightforward (we can use the 


schemes illustrated in Figure 42 on page 98 and Figure 44 on page 99), and is left as the 
traditional “exercise for the reader”. 
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¢ Macro BBit0n optimizes generated instructions (most error checks 
omitted) 


Two “passes” over bit name list: 


Scan and names, determine byte numbers 
If multiple bytes, generate “skip” tests/branches and label 


Macro 

BBitOn @NL,&T Bit Name List, Branch Target 
Aif (N‘&SysList ne 2 or '8NL' eq '' or ‘'&T' eq '').BadArg 
SetC ‘&Lab' Save label 

SetA 6 No. of distinct Byte Nos. 
SetA 6 Name counter 

SetA N'&NL Number of names provided 

Aif (8M ge &NN).Pass2 Check if all names scanned 
chiar iis (cont inued) 
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Bit-Handling Macros: Branch if Bits ON ... 


SetA é8H+1 Step to next name 

"SNL (8M) ' Pick off a name 

&(BitDef_&B8. ByteNo) Declare GBLA with Byte No. 

(&(BitDef &8. ByteNo) eq 6).UnDef Exit if undefined 

8 Loop through known Byte Nos 

(&K ge 8NBN) .NewBN Not in list, a new Byte No 

&K+1 Search next known Byte No 

(&BN(&K) ne &(BitDef_&B. ByteNo)).BNLp Check match 

1 Check if name already specified 

&J gt &IBN(&K)).Nm0K Branch if name is unique 

'&B' eq '&(BitDef_Nm &BN(&K). &J)').DupNm Duplicated 
Search next name in this byte 
Check further for duplicates 
-DupNm MNote 8, 'BBitOn: Name '‘'&B'' duplicated in operand list' 


MExit 
-Nm0K ANop , No match, enter name in list 
SIBN(&K) SetA &IBN(&K)+1 Have matching BN, count up by 1 
LclC &(BitDef Nm &BN(&K). &IBN(&K)) Slot for bit name 
&(BitDef Nm &BN(&K). &IBN(&K)) SetC '&B' Save K'th Bit Name, this byte 
Ago’ .NMLp Go get next name 
PS as -<-- (cont inued) 


July 1993 High Level Assembler Tutorial Guide 
© Copyright 1BM Corporation 1893 


Macro Techniques 111 


Bit-Handling Macros: Branch if Bits ON ... @ 


-NewBN ANop , New Byte No 
&NBN SetA 8&NBN+1 Increment Byte No count 
&BN(8&NBN) SetA &(BitDef &B. ByteNo) Save new Byte No 
S&IBN(&NBN) SetA 1 Set count of this Byte No to 1 
LclC &(BitDef Nm &BN (8NBN) ._ 1) Slot for first bit name 
&(BitDef_Nm &BN(&NBN). 1) SetC ‘ss’ Save Ist Bit Name, this byte 
“Ago  .NMLp Go get next name 
.Pass2  ANop , Pass 2: scan Byte No list 
&H SetA 6 Byte No counter 
&Skip SetC '‘Off&SysNdx' False-branch target 
y Aif on A &NBN) . Done Check if all Byte Nos done 
SetA Increment outer—loop counter 
SetA 28H (2H) Get M-th Byte No 
SetA 1 Set up inner loop “ 
SetC '&(BitDef_Nm &X. &K).,L''&(BitDef_Nm_&X._&K)' Operand 
Aif i Ab SIBN(EM)) GenBr Operand loop, check for done 
SetA Step to next bit in this byte 
Setc “sip. +L''&(BitDef_Nm_&X. &K)' Add next bit to operand 
Ago .OpLp Loop (inner) for next operand 
== (continued) 
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Bit-Handling Macros: Branch if Bits ON ... 


-GenBr ANop , Generate instruction for Byte No 
Aif (8 eq 8NBN).Last Check for last test 
&L &0p Test if bits are ON 
Skip if not all ON 
&L Nullify label string 
Loop (outer) for next Byte No 
. Las Generate last test and branch 
&L Test if bits are ON 
Branch if all ON 
(8NBN eq 1).Done No skip target if just 1 byte 
6H'6 Skip target 


8, "BBitOn: Name ''&B°' not defined by BitDef' 


8, 'BBitOn: Improperly specified argument list' 


July 1893 High Level Assembier Tutorial Guide 
© Copyright IBM Corporation 1993 


Using Declared Bit Names in a BBitOn Macro 
The BBitOn macro is intended to branch to a specified label if all the specified bit names are 
“on”, and should use the minimum number of instructions; the calling syntax is the fol- - 
lowing: 
BBitOn (Bit _Name_List),Branch Target 


and we will accept a single non-parenthesized bit name for the first argument. 


This macro will require a slightly different approach from the one used in the Bit0On macro: if 
any of the bits have been allocated in different bytes, we must invert the “sense” of all gen- 


erated branch instructions except the last. To see why this is so, suppose we wish to 
branch to XX if both BitA and BitB are “true”, and the two bits have been allocated in the 
same byte: 
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DC B'Q' 


BitA Equ. *,X'O1' Allocate BitA 
BitB Equ *,X'2Q! Allocate BitB 


™ BitA,L'BitAtL'BitB Test BitA and BitB 
BO XX Branch if both are ON 


and we see that only a single test instruction is needed. Now, suppose the two bits have 
been allocated to distinct bytes: 


DC B'0' 

BitA Equ *,X'Q1' Allocate BitA 
DC B'0' 

BitB Equ *,X'20! Allocate BitB 


Then, to branch if both are true, we must use two test instructions: 


™  BitA,L*BitA Check BitA 

BNO Not True Skip-Branch if not 1 

™ BitB,L'BitB BitA is 1; check BitB 

BO XX Branch to XX if both are 1 
Not_True DC QH'@' Label holder for "skip" target 


The implementation of the BBit0n macro uses a scheme similar to that in the BitOn macro: 
the list of bit names in the first argument will be extracted, and the same list of variables will 
be constructed. The second “pass” will need some modifications: 


If more than one pair of test and branch instructions will be generated, a “not true” 
label must be used for all branches except the last, and the label must be defined fol- 
lowing the final test and branch. 


The sense of all branches except the last must be “inverted” so that a branch will be 
taken to the target label only if all the bits tested have been determined to be “true”. 
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.DupNm 


. NmOK 


RIBN(&K) 


Macro 


BBitOn &NL,&T 


Aif 
SetC 
SetA 
SetA 
SetA 
Aif 
SetA 
SetC 
GblA 
Aif 
SetA 
Aif 
SetA 
Aif 
SetA 
Aif 
Aif 
SetA 
Ago 
MNote 
MExit 
ANop 
SetA 
LclC 


Bit Name List, Branch Target 
(N'&SysList ne 2 or '&NL' eq '' or '&T' eq '').BadArg 


'&Lab' Save label 

0 No. of distinct Byte Nos. 
C) Name counter 

N'&NL Number of names provided 
(& ge &NN).Pass2 Check if all names scanned 
&M+1 Step to next name 


'&NL (8M) ' Pick off a name 
&(BitDef_&B. ByteNo) Declare GBLA with Byte No. 
(&(BitDef_&B. ByteNo) eq 0).UnDef Exit if undefined 


0 Loop through known Byte Nos 
(&K ge &NBN).NewBN Not in list, a new Byte No 
&K+1 Search next known Byte No 


es ne &(BitDef_&B. ByteNo)).BNLp Check match 
Check if name already specified 

ie gt &IBN(&K)).NmOK Branch if name is unique 

('&B' eq '&(BitDef Nm &BN(&K). &J)').DupNm Duplicated 


&J+1 Search next name in this byte 
.CkDup Check further for duplicates 
8,'BBitOn: Name ''&B'' duplicated in operand list' 

; No match, enter name in list 
&IBN(&K)+1 Have matching BN, count up by 1 


&(BitDef_Nm &BN(&K). &IBN(&K)) Slot for bit name 


&(BitDef_Nm &BN(&K). &IBN(&K)) SetC '&B' Save K'th Bit Name, this byte 


. NewBN 
&NBN 


&BN(&NBN) SetA &(BitDef &B. ByteNo) 
&IBN(&NBN) SetA 1 


&(BitDef_Nm &BN(&NBN). 1) SetC ‘8B! 


Ago 
ANop 
SetA 


LclC 


Ago 


»NMLp Go get next name 
; New Byte No 
&NBN+1 Increment Byte No count 


Save new Byte No 

Set count of this Byte No to 1 
&(BitDef_Nm &BN(&NBN). 1) Slot for first bit name 

Save lst Bit Name, this byte 
~NMLp Go get next name 


Figure 54 (Part 1 of 2). Bit-Handling Macros: Macro to Branch if Bits are ON 
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Pass 2: scan Byte No list 
Byte No counter 
'OfF&SysNdx! False-branch target 
(& ge &NBN).Done Check if all Byte Nos done 
&M+1 Increment outer-loop counter 
&BN (&M) Get M-th Byte No 
1 Set up inner loop 
'&(BitDef_Nm_&X. &K).,L''&(BitDef_Nm_&X._&K)' Operand 
(&K ge &IBN(&M)).GenBr Operand loop, check for done 
&K+1] Step to next bit in this byte 
'80p.+L''&(BitDef_Nm_&X. &K)' Add next bit to operand 
.OpLp Loop (inner) for next operand 
‘ Generate instruction for Byte No 
(&M eq &NBN).Last Check for last test 
&0p Test if bits are ON 
&Skip Skip if not all ON 
us Nullify label string 
Loop (outer) for next Byte No 
Generate last test and branch 
Test if bits are ON 
Branch if all ON 
(&NBN eq 1).Done No skip target if just 1 byte 
QH'O' Skip target 


8, 'BBitOn: Name ''&B'' not defined by BitDef' 


8,'BBitOn: Improperly specified argument list! 


Figure 54 (Part 2 of 2). Bit-Handling Macros: Macro to Branch if Bits are ON 


some examples of calls to the BBitOn macro are shown in the following figure; the generated 


instructions are indicated by “+” characters in the left margin: 


Macro Techniques 


115 


116 


BBitOn b1,TB5 
™ b1,L'bl Test if bits are ON 
BO TB5 Branch if all ON 


BBitOn (c5,c4,c3,c2),tb7 
T™ c5,L'c5+L'c4+L'c3+L'c2 Test if bits are ON 
BO tb7 Branch if all ON 


BBitOn (bl,c2,b2,c3,b3,b4,c4,b5,c5) ,tb4 

™ b1,L'b1+L'b2+L'b3+L'b4+L'b5 Test if bits are ON 
BNO Off0051 Skip if not all ON 

T™ c2,L'c2+L'c3+L'c4+L'c5 Test if bits are ON 

BO tb4 Branch if all ON 


+0ff0051 DC 0H'O' Skip target 
TB7 BBitOn (b1,b2,b3,b4,b5,b6,b7),tb7 


BBitOn (b1l,c2,b2,c3,d4,e2) ,tb7 
b1,L'b1i+L'b2 Test if bits are ON 
Of f0054 Skip if not all ON 
c2,L'c2t+L'c3 Test if bits are ON 
Of f0054 Skip if not all ON 
d4,L'd4 Test if bits are ON 
Of 0054 Skip if not ali ON 
e2,L'e2 Test if bits are ON 
tb7 Branch if all ON 

+0ff0054 DC QH'Q' Skip target 


++eetete te + 


. Figure 55, Bit-Handling Macros: Examples of Calls to BBitON Macro 


The extension of the BBitOn macro to a similar BBitOff macro is simple, and is also left as 
an exercise. 


In summary, this final set of macros can be used to define, manipulate, and test bit flags 
with reliability and efficiency. 
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Using and Defining Data Types 


¢ We’re familiar with type sensitivity in higher-level languages: 
- Instructions generated from a statement depend on data types: 
A=B+C 
- A, B, C might be integer, float, complex, boolean, string, ... 


‘ Most “named objects” in the assembler language have a “type 
attribute” 


- Can exploit type attribute references for type-sensitive instruction 
sequences 


Extensions to the “base language” types are possible: 


'-- . Assign our own type attributes (avoiding conflicts with Assembler’s) 
- Utilize created variable symbols to retain “user type” information 
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Using and Defining Data Types 


One of the most useful features of the macro language is that it allows you to write macros 

& whose behavior depends on the “types” of its arguments. A single macro definition can gen- 
ao erate different instruction sequences; depending on what it can determine about its argu- 

ments. This behavior is common in most higher-level languages; for example, the statement 


A=B+C 


may generate very different instructions depending on whether the variables A, B, and C 
have been declared to be integer, floating, complex, boolean, or character string (or mix- 
tures of those, as in PL/I). We will see that macros offer the same flexibility and power. 
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Base-Language Type Sensitivity 


Macro , Increment &V by amount &A (default 1) 
INCR &V,&A,&Reg=6 Default work register = 6 
SetC &V Type attribute of lst arg 
SetC Save type of &V for memonic suffix 
SetC Default increment 
Aif ('&A' eq '').IncOK Increment now set 0K 
SetC ‘&A' Supplied increment (N.B. Not SETA!) 
-Inc0K Aif ('&T' eq 'F').F,('&T' eq 'P').P, 
('&T' eq 'H' or ‘'&T' eq 'D' or ‘&T' eq ‘'E').T 
MNote 8, 'INCR: Cannot use type '‘&T'' of ‘‘&V''.' 
MExit 
ANOP , Type of &V is F 
SetC '' Null operation suffix 
ANOP , Register-types D, E, H (and F) 
L&0p &Reg,&V Fetch variable to be incremented 
A&Op &Reg,=&T. ‘'&I' Add requested increment 
ST&Op &Reg, &V Store incremented value 
MExit 
ANOP , Type of &V is P 
AP ' &V,=P°SI' Increment packed variable 
MEn 
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The assembler’s assignment of type attributes to most forms of declared data lets us write 
macros that utilize the type information to make decisions about the instructions to be gen- 
erated: For example, suppose we want to write a macro INCR to add a constant value to a 

variable, with default increment 1 if no value is specified in the macro call. Consider 

Figure 56: , : 


&V ,&A, &Reg=0 
T'&V Type attribute of list arg 
ray! Save type of &V for mnemonic suffix 
i Default increment 
('BA' eq '').IncOK Increment now set OK 
"SA! Supplied increment (N.B. Not SETA!) 
('&T' eq 'F').F,('&T' eq 'P').P, 
('&T' eq 'H' or '&T' eq 'D' or '&T' eq 'E').T 
8,'INCR: Cannot use type ''&T'' of ''&V''.”! 


; Type of &V is F 

is Null operation suffix 

; Register-types D, E, H (and F) 
&Reg, &V Fetch variable to be incremented 
&Reg,=&T. '&l' Add requested increment 

&Reg, &V Store incremented value 


; Type of &V is P 
&V,=P'&I! Increment variable 


Figure 56. Macro Type Sensitivity to Base Language Types 
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The macro first determines the type attribute of the variable &V, and sets the increment 
value &l. The type attribute is checked for one of the five allowed types: D, E, F, H, and P. 
Finally, an instruction sequence appopriate to the variable’s type is generated to perform the 
requested incrementation. This macro “works” because we can use the type attribute infor- 
mation about the variable &V to create a literal of the same type. 


An observation: this macro represents a form of polymorphism in the sense that the opera- 
tion it performs depends on the type(s) of its argument(s). 


Examples Using Assembler-Assigned Types 


¢ INCR macro examples 


Day of the week 
Rate of something 


MyPay DS PL6 My salary 
Dist oS Dd A distance 
Wt DS E A weight 


Type not valid for INCR macro 
Test with invalid type 


cc INCR Day Add 1 to Day 
oD INCR Rate,-3,Reg=15 Decrease rate by 3 
INCR MyPay,150.58 Add 156.56 to my salary 


JJ INCR Dist,—-3.16227766 Decrease distance by sqrt(16) 
KK Incr Wt,-2E4,Reg=6 Decrement weight by 16 tons 


e The macro “works” because the generated literal has the “right” type 
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Some examples of calls to the INCR macro are shown in the following figure. 


: H Day of the week 
Rate ODS F Rate of something 
MyPay DS PL6 My salary 
Dist DS D A distance 
Wt DS E A weight 
X Type not valid for INCR macro 


BB INCR XXX,2 Test with invalid type 


cc INCR Day Add 1 to Day 
DD INCR Rate,-3,Reg=15 Decrease rate by 3 
INCR MyPay, 150.50 Add 150.50 to my salary 
JJ INCR Dist,-3.16227766 Decrease distance by sqrt(10) 
KK Incr Wt,-2E4,Reg=6 Decrement weight by 10 tons 


Figure 57. Examples: Macro Type Sensitivity to Base Language Types 


Type sensitivity of this form can be used in many applications, and can help simplify 
program logic and structure. 
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Problems Using Assembler-Assigned Types 


¢ Assembler types might not conform directly! 


- Data type conversions may be required? How will we know? 


Rate DS F Rate of something 
MyPay DS PL6 My salary 
ADD2 MyPay,Rate Add binary Rate to packed MyPay ?? 


¢« Assembler data types know nothing about “meaning” of variables 


Day H Day of the week 
Rate 0S F Rate of something 
Dist DS D A distance 
Wt DS E A weight 
ADD2 Rate, Day Add binary Day to Rate (??) 
ADD2 Dist,WT Add floating Distance to Weight (7?) 
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Shortcomings of Assembler-Assigned Types 


There are many benefits achievable from utilizing assembler type attributes. Suppose, 
however, that we wish to add two variables using a macro named ADD2 that works like the 
INCR macro just described. Two problems arise: 


_- 1. . The types of the variables to be added may not “conform” by having the same 
assembler-assigned type attribute. For example, let some variables be defined as in 
Figure 56 on page 118: _ 


Rate ODS F Rate of something 
MyPay DS PL6 My salary 


Then, if we can write a macro call like 
ADD2 MyPay,Rate Add binary Rate to packed MyPay 


then some additional conversion work is needed because the types of the two variables 
do not allow direct addition. Such conversions are sometimes easy to program, either 
with inline code or with a call to a conversion subroutine. However, as the number of 
allowed types grows, the number of needed conversions may grow almost as the 
square of the number of types. 


2. The more serious problem is that the assembler-assigned types may conform, but the 
programmer's “intended types” may have no sensible relationship to one another! Con- 
sider the same set of definitions: 


Day DS H Day of the week 
Rate DS F Rate of something 
Dist DS D A distance 

Wt DS E A weight 


Then, is is clear that we can write simple macros to implement these additions: 


ADD2 Rate,Day Add binary Halfword to Fullword 
ADD2 Dist,WT Add floating Distance to Weight 
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because the data types conform: halfword and fullword binary additions and short and 
long floating additions are supported by hardware instructions. 


Consider, however, what is being added: in the first example, we are adding a “day” to 
a “rate” and in the second we are adding a “distance” to a “weight”, and neither of 
these operations makes sense in the real world, even though a computer will blindly 
add the numbers representing these quantities. 


Data Typing with User-Assigned Type Attributes 


e Use third operand of EQU statement for type assignment: 


symbol EQU expression, length, type 


Declaration of DATE types made by Dc1lDate macro 


Macro 

DclDate . 

GhIC &DateTyp Type attr of “Date” variable 
&DateTyp SetC C'd' Type attr is lower case '‘d' 
&DateLen SetA 4 Dates stored in 4 bytes 

SetA N'&SysList Number of arguments to declare 

SetA 86 Counter 

Aif A 1% &NV) . Done Check for finished 

SetA Increment argument counter 

oc pisatales: ‘@' Define rs bs 
&SysList(&K) EQU *-&DateLen. ,&Datelen. ,aDateTyp Define name, Tength, type 

Ago «Test 
.Done MEnd 
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Data Typing with User-Assigned Type Attributes ... 


¢ Declaration of PERIOD types made by DclPerd macro 


Macro 
DclPerd &Init=6 Optional initialization value 
GbIC &PerdTyp Type attr of “Period” variable 
LelA &PerdLen Length of a "Period" variable 
&PerdTyp SetC C'p' Type attr is lower case 'p' 
&PerdLen SetA 3 Pericds stored in 3 bytes 
SetA N'&SysList Number of arguments to declare 
SetA 6 Counter 
Aif a ge 8&NV).Done Check for finished 
SetA Increment argument counter 
oC pLierdLen. "aInit.' Define storage 
i a EQU *-&PerdLen. ,&PerdLen. ,&PerdTyp Define name, length, type 
Ago. Test 
.Done MEnd 


Initial value can be specified with Init= keyword 
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User-Defined Type Attributes 


One can obtain some (minor) relief from the limitations of the Assembler’s assignment of 
type attributes by using the third operand of an EQU statement to assign user-defined type 
attributes to program objects. As a reminder, the full syntax of the EQU statement is 


symbol EQU  expression[,[length][,type expression]] 


The type_expression in the third operand must evaluate to an absolute quantity in the range 
from 0 to 255. 


To overcome the limitations of using just assembler-assigned types, we will examine a set of 
macros that declare and operate on data items with just two specific types: calendar dates, 
and periods of elapsed time in days. With these two data types, we can perform certain 
kinds of arithmetic and comparisons: 


e two dates may be subtracted to yield a period 
* a period may be added or subtracted from a date to yield a date 
e two periods may be added or subtracted 


e dates may be compared with dates, and periods with periods 
Any other operation involving dates and periods is invalid. 


First, we will examine two macros that “declare” variables of type “date” and “period”, 
(DciDate and DclPerd, respectively). Each macro will accept a list of names to be declared 
with that type, assign “private” type attributes C'd' and C'p', and allocate storage for the 
variables. 


First, we will illustrate a macro DclDate to declare variables of type “date”. 


Macro 
Dc] Date 
GbiC &DateTyp Type attr of "Date" variable 
&DateTyp SetC C'd' Type attr is lower case ‘d' 
&DateLen SetA 4 Dates stored in 4 bytes 
&NV SetA N'&SysList Number of arguments to declare 
&K SetA 0 Counter : 
Test (&K ge &NV).Done Check for finished 
&K &K+1 Increment argument counter 
PL&DateLen. '0' Define storage 
&SysList(&K) EQU *-&DateLen.,&DateLen. ,&DateTyp Define name, length, type 
Ago .tTest 
.Done MEnd 
* 
DclDate Birth,Hire,Degree,Retire,Decease Declare 5 date fields 
DciDate LoanStart,LoanEnd Declare 2 date fields 


Figure 58. Macro to Declare “DATE” Data Type 


The DclDate macro accepts a list of names, and allocates a packed decimal storage of 4 
bytes for each. 


The DclPerd macro also accepts a list of names, and allocates a packed decimal field of 3 


bytes for each; in addition, a keyword variable &lnit can be used to supply an initial value for 
all the variables deciared on any one macro call. 
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Macro 
DCLPERD &lInit=0 Declare a time period in days 
GbiC &PerdTyp Type attr of "Period" variable 
LclA &PerdLen Storage length of elapsed periods 
&PerdTyp SetC C'p' Type is lower case 'p' 
&PerdLen 3 Length is 3 bytes 


is &NV N'&SysList Number of names to declare 
&K Q Counter 
Test (&K ge &NV).Done Check for finish 


&K &K+1 Increment argument count 
PL&PerdLen.'&Init' Declare variable and initial value 
&SysList(&K) EQU *-&PerdLen.,&PerdLen.,&PerdTyp Declare name, length, type 
Ago Test Check for more arguments 
.Done MEnd 
* 
Aaa DclPerd Vacation,Holidays 
DclPerd LoanTime 
DclPerd Year, Init=365 
DclPerd Week, Init=7 


Figure 59. Macro to Declare “PERIOD” Data Type 


Calculating Date Variables: CalcDat Macro 


° Define user-called CalcDat macro to calculate dates: 


&AnsDate CalcDat &Argl, Op, &Arg2 Calculate a Date variable 


Allowed forms are: 


Date CalcDat Date,+,Period Date = Date + Period 
Date CalcDat Date,-,Period Date = Date - Period 
Date CalcDat Period,+,Date Date = Period + Date 


CalcDat will validate types, and call two auxiliary macros: 


DATEADDP Datel,Lenl,Peritod,LPer,AnsDate,LenAns Date+Per -—> Date 
DATESUBP Datel,Lenl,Period,lPer,AnsDate,LenAns Date-Per —> Date 


- Auxiliary service macros “understand” data representations 
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Calculating Date Variables: CalcDat Macro ... 


e Calculate Date=Date+Period or Period+Date 


Macro , Error checks omitted 

&Ans CALCDAT &Argl, &0p, &Arg2 Calculate a date in &Ans 
GhiC &PerdTyp,&DateTyp Type attributes 

&T1 SetC T'&Argl Save type of &Argl 

&T2 SetC T'&Arg2 And of &Arg2 
Aif ('&T1&T2' ne ‘&DateTyp&PerdTyp' and 

‘&T1&T2' ne '&PerdTyp&DateTyp').Err4 Validate types 

Aif ('&0p' eq '+').Add Check for add operation 
tad &Argl, L'&Argl,&Arg2,L'SArg2,8Ans,L'&argl 0-P—>D 
MExit 
AIF (‘&T1' eq '&PerdTyp').Add2 Ast opnd is period of days 
DATEADOP &Argl,L'&Argl, &Arg2,L'&Arg2,&Ans,L'8Argl 0+P—>D 
MExit 
DATEADDP &Arg2,L'&Arg2,&Argl, L'&Argl,&Ans,L'&Arg2 P+D—>D 
MExit 
MNote 8,'CALCDAT: Incorrect declaration of Date or Period?' 
MEnd 
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Having written macros to declare the two data types, we can now consider macros for doing 
calculations with them. First, we will examine a date-calculation macro CALCDAT, with the 
following syntax: 


&AnsDate CalcDat &Argl,0p,&Arg2 Calculate a Date variable 


where &AnsDate must have been declared a “date” variable, and the allowed operand com- 
binations are: 


Date CalcDat Date,+,Period 
Date CalcDat Period,+,Date 
Date CalcDat Date,-,Period 


We are now in a position to write a CalcDat macro that validates the types of all three oper- 
ands before setting up the actual computations which will be done by two “service” macros 
called DATEADDP (to add a period to a date) and DATESUBP (to subtract a period from a date). 
These service macros will “understand” the actual representation of “date” and “period” 
variables, and can perform the operations accordingly. 
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. Macro 
@ &AnS CALCDAT &Arg1,&0p, &Arg2 Calculate a date in &Ans 
&M SetC 'CALCDAT: ! Macro name for messages 
GbiC &PerdTyp,&DateTyp Type attributes 
Aif  (N'&SysList ne 3).Errl Check for required arguments 
Aif ('&0p' ne '+' and '&Op' ne '-').Err2 
Aif (T'&Ans ne ‘&DateTyp').Err3 


&T1 SetC T'&Argl Save type of &Argl 
&T2 SetC T'&Arg2 And of &Arg2 
Aif ('&T1&T2' ne '&DateTyp&PerdTyp' and X 
~ '&T1&T2' ne '&PerdTyp&DateTyp').Err4 Validate types 
Aif ('&0p' eq '+').Add Check for add operation 


Aif ('&T1&T2' ne '&DateTyp&Perdtyp').Err5 Bad operand seq? 
DATESUBP &Arg1,L'&Argl,&Arg2,L'&Arg2,&Ans,L'&argl D-P-->D 
MExit | 

. Add AIF ('&Tl' eq '&PerdTyp').Add2 1st opnd a period of days 
DATEADDP &Arg1,L'&Arg1,&Arg2,L'&Arg2,&Ans,L'&Argl D+P-->D 
MExit 

.Add2 DATEADDP &Arg2,L'&Arg2, &Argl,L'&Argl,&Ans,L'&Arg2 P+D-->D 
MExit 

~Errl MNote 8,'&.Incorrect number of arguments' 
MExit 

~Err2 MNote 8,'&M.QOperator ''&Op'' not + or -' 
MExit 

-Err3  Aif = (T'&Ans eq '0').Err3a Check for omitted target 
MNote 8,'&.Target ''&Ans'' not declared by DCLDATE' 
MExit 

-Err3A  MNote 8,'&M.Target Date variable omitted from name field' 
MExit 

~Err4 MNote 8,'&M.Incorrect declaration of Date/Period arguments' 
MExit 

~Errd MNote 8,'&.Subtraction operands in reversed order' 
MEnd 


Figure 60. Macro to Calculate “DATE” Results 


Some examples of calls to the CalcDat macro are shown in the following figure. 


CalcDat Degree,+, Year 


CalcDat Year,+,Degree 
CalcDat Degree,-,Year 


Figure 61. Examples of Macro Calls to Calculate “DATE” Results 


Macro Techniques 125 


126 


Calculating Period Variables: CalcPer Macro 


¢ Define user-called CalcPer macro to calculate periods 


Allowed forms are: 


Period 
Period 
Period 
Period 
Period 


CalcPer Date,-—.Date 

CalcDat Period,+,Peritod 
CalcDat Period,—,Period 
CalcDat Period,*,Number 
CalcDat Period, /,Number 


Difference of two date variables 
Sum of two period variables 
Difference of two period variables 
Product of a period and a number 
Quotient of a period and a number 


CalcPer will validate types, and call five auxiliary macros: 


PERDADOP 
PERDSUBP 
PERDMULP 
PERDDIVP 
DATESUBD 


Perl, Lenl, Per2,Len2,AnsP, LenAns 
Perl, Lenl,Per2,Len2,AnsP, LenAns 
Perl, Lenl, Per2, Len2, AnsP, LenAns 
Perl, Lenl,Per2,Len2,AnsP, LenAns 


Per +Per 
Per —Per 
Per *Num 
Per /Num 


Datel, Lenl,Period,LPer,AnsDate,LenAns Date-Date 


July 1993 


High Level Assembler Tutorial Guide 


© Copyright IBM Corporation 1993 


Calculating Period Variables: CalcPer Macro ... 


Macro 
&Ans CALCPER &Argl,&0p, &Arg2 
GhiC &PerdTyp,&DateTyp 
&X(C'+') SetC ‘ADD' 
&X(C'-") SetC '‘SUB' 
&X(C'*') SetC 'MUL' 
ae /') Setc ‘DIV' 
SetC "Cr 'BOp''' 
aT SetC T'&Argl 
&T2 SetC T’&Arge 


Type attributes 
Name for Add routine 


Convert &0p char to SDT 
Type of Argl 
Type of Arg2 


yp 
Aif Bana eq "&DateTyp&DateTyp.—'). OD Chk date-date 
PP 


Aif '&T2' ne 


Second operand nonnumer ic 


PERD&X(&Z) .P arate L' gArgl, =PL3'&Arg2',3,&Ans,L'&Ans P op const 


MExit 


PERD&X(&Z).P &Argl,L'&Argl, &Arg2,L'&Arg2,&Ans,L'&Ans P op P 


MExit 


DATESUBD &Argl,L'&Argl, &Arg2,L'SArg2,&Ans,L'&Ans date-date 


MEnd 
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A second macro CalcPer to calculate periods of time is similar in concept, but somewhat 
more complex because of a greater allowed set of operand combinations: 


&AnsPerd CalcPer &Arg1,0p,&Arg2 


Calculate a Period variable 


where &AnsPerd must have been declared a “period” variable, and the allowed operand 


combinations are: 


Period CaicPer Date,-.Date 

Period CalcDat Period,+,Period 
Period CalcDat Period,-,Period 
Period CalcDat Period,*,Number 
Period CalcDat Period, /,Number 


Difference of two date variables 
Sum of two period variables 
Difference of two period variables 
Product of a period and a number 
Quotient of a period and a number 


The CalcPer macro validates its arguments before generating calls to the “operational” 


macros that do the actual arithmetic. 
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& Macro 
&Ans CALCPER &Arg1,&0p,&Arg2 


GbIC &PerdTyp, &DateTyp Type attributes 
&M SetC 'CALCPER: ' Macro name for messages 
Aif (N'&SysList ne 3).Erri Wrong number of arguments 
Aif (T'&Ans ne 'p').Err2 Invalid target 
z Aif (T'&0p ne 'U' or K'&Op ne 1).Errs Invalid operator 
&X(C'+') SetC 'ADD' Name for Add routine 


aX(C'=") SetC ‘SUB! 
ax(C'*') SetC "MUL! 


. &X(C'/') SetC 'DIV' 
&Z SetC 'C''&Op''!! Convert &0p char to SDT 
&T1 SetC T'&Argl Type of Argl 
&T2 SetC T'&Arg2 Type of Arg2 
Aif ('&T1&T2&0p' eq '&DateTyp&DateTyp.-').DD Chk date-date 
Aif  (‘'&T1' ne ‘&PerdTyp').Err3 Invalid first operand 
Aif  ('&T2' eq '&PerdTyp' and X 


('&0p' eq 't+' or '&0p' eq '-')).PP 
Aif ('&0p' eq 't+' or '&0p' eq '-' or '&0p' eq '*').0pOK, X 
('&Op' ne '/').Errsd 
. Op0K Aif  ('&T2' ne 'N').Err4 Second operand nonnumeric 
x Third operand is a constant 
PERD&X(&Z).P Arg1,3,=PL3'&Arg2',3,&8Ans,3 period op const 


MExit 
~PP PERD&X(&Z).P &Arg1,3,&Arg2,3,&8Ans,3 period op period 
MExit 
.DD DATESUBD &Argl,4,&Arg2,4,&Ans,3 Difference of 2 dates 
MExit 
~Errl MNote 8,'&. Incorrect number of arguments' 
MExit | 
-Err2 Aif  (T'&Ans ne '0').Err2A Check for omitted target 
MNote 8,'&.Target variable omitted' 
MExit 
~Err2A MNote 8,'&.Target ''&Ans'' not declared by DCLPERD' 
MExit 
~Err3 MNote 8,'&M.First argument invalid or not declared by DCLPERD' 
MExit 
~Err4 MNote 8,'&M.Third argument invalid or not declared by DCLPERD' 
MExit 
~Errs MNote 8,'&M.Invalid (or missing) operator ''&Op''' 
MEnd 


Figure 62. Macro to Calculate “PERIOD” Results 


CALCPER Year,+, Year Period + Period 
CALCPER Hire,-,Degree Date - Date 
7 CALCPER Hire,-,Hire Date - Date 


CALCPER Year,-,Year Period - Period 


CALCPER Year,+,10 Period + Number 
CALCPER Year,-,10 Period - Number 
CALCPER Year,*,10 Period * Number 
CALCPER Year,/,10 Period / Number 


Figure 63. Examples of Macro Calls to Calculate “PERIOD” Results 
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As you can see, these macros provide a fairly strong degree of type checking of their argu- 

ments to ensure that they conform to the sets of operations appropriate to their types. If we 

had written only machine instructions, the opportunities for operand type conflicts, or © 
operator-operand conflicts, would not only have been larger, but might have gone unde- 

tected. In addition, once a set of useful macros has been coded, you can think in terms of 

“higher level” operations, and avoid the many details necessary to deal with the actual 

machine instructions. 
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e System (&SYS) Variable Symbols 


System variable symbols are a special class of variable symbols, starting with the charac- 
ters &SYS. They are “owned” by the assembler: they may not be declared in LCLx or GBLx 
statements, and may not be used as symbolic parameters. Their values are assigned by the 
assembler, and never by SETx statements. 


High Level Assembler provides many new system variable symbols: nineteen will be new to 
users of the H-Level Assembler, and three additional symbols will be new to users of the 
DOS/VSE Assembler. Four symbols are available in all three assemblers: &SYSECT, 

1 &SYSLIST, &SYSNDX, and &SYSPARM. Figure 64 on page 131 summarizes their properties. 


System Variable Symbols: Overview 


¢ Symbols whose value is defined by the assembler 
- Four available with the “original” (1966) assemblers 
- Assembler H (1970) added three 
~ High Level Assembler provides 19 new symbols 
¢ Characteristics include 
Type (arithmetic, boolean, or character) 
Type attributes (mostly 'U' or '0') 
Scope (usable in macros only, or in open code and macros) 


Variability (when and where values might change) 
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System Variable Symbols: Properties 


The symbols have a variety of characterizations: 
e = Availability 


Four symbols are available in all (designated “All”) assemblers for the 
System/360/370/390 family of processors. Three others are available in Assembler H 
(designated “AsmH”); High Level Assembler provides the richest set of twenty-six 
system variable symbols (designated “HLA”). 


‘ e Type 


Most symbols have character values, and are therefore of type C: that is, they would 
normally be used in SETC statements or in similar contexts. A few, however, have arith- 

. metic values (type A) or boolean values (type B). &SYSDATC and &SYSSTMT are nomi- 
nally type C, but may also be used as type A. 


e Type attributes 


Most system variable symbols have type attribute U (“undefined”) or 0 (“omitted”, 
usually indicating a null value); some numeric variables have type N. The exception is 
&SYSLIST: its type attribute is determined from the designated list item. 


e Scope of usage 
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Some symbols are usable only within macros (“local” scope), while others are usable 
both within macros and in open code (“global” scope). 


e Variability 


some symbols have values that do not change as the assembly progresses. Normally, 
such values are established at the beginning of an assembly. These values are denoted 
“Fixed”. Note that all have Global scope. 


Other symbols have values that may change during the assembly. These values might 
be established at the beginning of an assembly or at some point subsequent to the 
beginning, and may change depending on conditions either internal or external to the 
assembly process. 


- Variables whose values are established at the beginning of a macro expansion, and 
for this the values remain unchanged throughout the expansion, are designated 
“Constant”, even though they may have different values in a later expansion of the 
same macro, or within “inner macros” invoked by another macro. Note that all have 
local scope. 


- Variables whose values may change within a single macro expansion are desig- 
nated “Variable”. Currently, this designation applies only to &SYSSTMT. 


These symbols have many uses: helping to control conditional assemblies, capturing envi- 


ronmental data for inclusion in the generated object code, providing program debugging 
data, and more. 
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Variable Symbol 
&SYSASM 
&SYSDATC 
&SYSDATE 


&SYSECT 
&SYSIN_DSN 


&SYSIN_MEMBER 
&SYSIN_VOLUME 


&SYSJOB 
&SYSLIB_DSN 
&SYSLIB_MEMBER 
&SYSLIB_VOLUME 


&SYSLIST 


&SYSLOC 


&SYSNDX 
| &SYSNEST 


&SYSOPT_DBCS 
&SYSOPT_OPTABLE 
&SYSOPT_RENT 
&SYSPARM 


&SYSSEQF 


&SYSSTEP 


Avail- 
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Content and Use 


Assembler name 


Assembly date, including 
century, in YYYYMMDD 
format 


Assembly date in MM/DD/YY 
format 


Current control section name 


Current primary input data 
set name 

Current primary input 
member name 


Current primary input data 
set name volume identifier 


Assembly job name 
Current library data set name 
Current library member name 


Current library data set 
volume identifier 


Macro argument list and indi- 


vidual list and sublist ele- 
ments 


Current location counter 
name | 


Macro invocation count 


Nesting level of the macro 
call 


Setting of DBCS invocation 
parameter 


Setting of OPTABLE invoca- 
tion parameter 


Setting of RENT invocation 
parameter 


Value provided by SYSPARM 
invocation parameter 


Sequence field of current 
open code statement 


Assembly step name 


Number of next statement to 


be processed 
Current control section type 


System on which assembly is 


Assembly start time 
Assembler version 


ua 


System Variable Symbols: Fixed Values © 


° &SYSASM, &SYSVER: describe the assembler itself 


e  &SYSTEM_ID: describes the system where the assembly is done 


&SYSJOB, &SYSSTEP: describe the assembly job 

&SYSDATC, &SYSDATE: assembly date 

&SYSTIME: assembly time (HH.MM) 7 
&SYSOPT_OPTABLE: which opcode table is being used 

&SYSOPT_DBCS, &SYSOPT_RENT: status of the DBCS and RENT options 

&SYSPARM: value of the SYSPARM option 
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Variable Symbols With Fixed Values During an Assembly 


&SYSASM and &SYSVER 


The &SYSASM symbol provides the name of the assembler. For High Level Assembler, the 
value of this variable is 


HIGH LEVEL ASSEMBLER 


The &SYSVER variable symbol describes the version, release, and modification of the 
assembler. A typical value of this variable might be 


1.1.0 


This pair of variables could be used to provide identification within an assembled program of 
the assembler used to assemble it: 


What_ASM DC C'Assembled by &SYSASM., Version &SYSVER..' 


&SYSTEM_ID 


The &SYSTEM_ID variable provides an identification of the operating system under which the = 
current assembly is being performed. A typical value of this variable might be 


MVS/ESA SP 4.2.0 . 


This variable could be used to provide identification within an assembled program of the 
system on which it was assembled: 


What_Sys DC C'Assembled on &SYSTEM ID..' @ 
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&SYSJOB and &SYSSTEP 


@ These two variables provides the name of the job and step under which the assembler is 
running. 


When assembling under the CMS system, the value of the &SYSJOB variable is always 
(NOJOB); and when assembling under the CMS or VSE systems, the value of the &SYSSTEP 
variable is always (NOSTEP). 


This pair of variables could be used to provide identification within an assembled program of 
the job and step used to assemble it: 


Who_ASM DC C'Assembled in Job &SYSJOB., Step &SYSSTEP..' 


&SYSDATC 


This provides the current date, with century included, in the format YYYYMMDD. A typical value 
of this variable might be 


19920626 


Observe that the &SYSDATE variable provides only two digits of the year, in the form 
MM/DD/YY. 


&SYSDATE 


&SYSDATE provides the current date, in the form MM/DD/YY. A typical value of this variable 
might be 


©} 06/26/92 


&SYSTIME 


The &SYSTIME variable provides the time at which the assembly started, in the form HH.MM. 


This variable, along with &SYSDATE or &SYSDATC, could be used to provide identification 
within an assembled program of the date and time of assembly: 


When ASM DC C'Assembled on &SYSDATC., at &SYSTIME..' 


&SYSOPT_OPTABLE 


This variable provides the name of the current operation code table being used for this 
assembly, as established by the OPTABLE option. A typical value of this variable might be 


ESA 
This variable is useful for creating programs that must execute on machines with limitations 
on the set of available instructions. For macro-generated code, this variable can be used to 
determine what instructions should be generated for various operations, e.g. BALR vs. BASR. 


This variable could be used to provide identification within an assembled program of the 
operation code table used to assemble it: 


What_Ops DC C'Opcode table for assembly was &SYSOPT_OPTABLE.. ' 
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&SYSOPT_DBCS and &SYSOPT_RENT 


The &SYSOPT_DBCS and &SYSOPT_RENT binary variables provide the settings of the DBCS 
and RENT options, respectively. Their values can be used to control the generation of 
instructions or data, or to help control the scanning of macro arguments. 


For example, character data to be included in constants can be generated with proper 
encodings if DBCS environments must be considered. Similarly, macros can use the setting 
of the RENT option to generate different instruction sequences for reentrant and 
nonreentrant situations. 


The &SYSOPT_RENT variable could be used to provide conditional assembly support for dif- 
ferent code sequences: 


AIF (&SYSOPT_RENT).Do_ Rent 
MYMAC Parml1,Parm2,GENCODE=NORENT Generate non-RENT code 
AGO .Continue 
~Do Rent MYMAC Parm1,Parm2,GENCODE=RENT Generate RENT code 
~Continue ANOP 


&SYSPARM 


The &SYSPARM variable symbol provides the character string provided by the programmer 
in the invoking parameter string, in the SYSPARM option: 


SYSPARM (string) 


This variable could be used to provide identification within an assembled program of the 
&SYSPARM value used to assemble it, as well as to control conditional assembly activities: @ 


What_PRM DC C'&&SYSPARM value was ''&SYSPARM.''.' 
X14 AIF  ('&SYSPARM' NE 'TRACE').Skip_Trace 


MNOTE ‘Assembly reached Sequence Symbol .X14' 
»Skip_Trace ANOP 
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®@ System Variable Symbols: Values Constant in Macros 


&SYSSEQF: sequence field of the statement calling the macro 
&SYSECT: section name active at time of call 

&SYSSTYP: section type active at time of call 

&SYSLOC: name of location counter active at time of call 


BSYSIN DSN, &SYSIN MEMBER, &SYSIN VOLUME: origins of current 
e primary input file 


&SYSLIB_DSN, &SYSLIB MEMBER, &SYSLIB VOLUME: origins of current 
library input file 


&SYSNEST: macro nesting level 
&SYSNDX: incremented by 1 at each macro call 


&SYSLIST: access to macro positional parameters and sublists 
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Variable Symbols With Constant Values Within a Macro 


@ &SYSSEQF 


The &SYSSEQF symbol provides the contents of the sequence field of the current input state- 
ment. This information can be used for debugging data. For example, suppose we have a 
macro which inserts information about the current sequence field into the object code of the 
program, and sets RO to its address (so that a debugger can tell you which statement was 
identified in some debugging activity). A macro like the following might be used: 


Macro 

&L DebugPtA 

&L BAS 0,*+12 Addr of Sequence Field in RO 
DC CL8'&SYSSEQF ! Sequence Field info 
MEnd 

B DebugPtA 


&SYSECT 


The &SYSECT symbol provides the name of the control section (CSECT, DSECT, COM, or 
RSECT) into which statements are being grouped or assembled at the time the referencing 
macro was invoked. If a macro must generate code or data in a different control section, 
this variable permits the macro to restore the name of the previous environment before 

™ exiting. (Note also its relation to &SYSSTYP.) An example illustrating &SYSECT and 
&SYSSTYP is shown below. 
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a et CSA CAA CCC 'cACcc AC CCC Z CT, 


&SYSSTYP 


The &SYSSTYP symbol provides the type of the control section into which statements are 
being grouped or assembled (CSECT, DSECT, or RSECT) at the time the referencing macro 
was invoked. If a macro must generate code or data in a different control section, this vari- 
able permits the macro to restore the proper type of control section for the previous environ- 
ment, before exiting. 


For example, suppose we need to generate multiple copies of a small DSECT. The macro 
shown in the following example generates the DSECT so that each generated name is pre- 
fixed with the characters supplied in the macro argument. The environment in which the 
macro was invoked is then restored on exit from the macro. 


Macro 

DSectGen &P 
&P.Sect DSect , Generate tailored DSECT name 
&P.F1 DS D DSECT Field No. 1 
&P.F2 DS 18F DSECT Field No. 2, a save area 
&SYSECT &SYSSTYP Restore original section 

MEnd 


&SYSLOC 


&SYSLOC contains the name of the current location counter, as defined either by a control 
section definition or a LOCTR statement. 


As in the example of &SYSSTYP, the &SYSLOC variable can be used to capture and restore 
the current location counter name. We again suppose in this example that we are inter- 
rupting the statement flow to generate a small DSECT: 


Macro 
DSectGen &P 

&P.Sect DSect Generate the DSECT name 

&P.F 1 DS D DSECT Field No. 1 

&P.F2 DS 18F DSECT Save Area 

&SYSLOC LOCTR Restore previous location counter 
MEnd 


&SYSIN_DSN, &SYSIN_MEMBER, and &SYSIN_VOLUME 


These three symbols identify the origins of the current primary input file. Their values 
change across input-file concatenations. This information can be used to determine reas- 
sembly requirements. 


The &SYSIN_DSN symbol provides the name of the current primary input (SYSIN) data set or 
file. 


The &SYSIN_MEMBER symbol provides the name of the current primary input member, if 
any. 


The &SYSIN VOLUME symbol provides the name of the current primary input volume. For 
example, the following SYSINFO macro will capture the name of the current input file, its 
member name, and the volume identifier. (If the input does not come from a library 
member, the member name will be replaced by the characters “(None)”.) 
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&L DC C'Input: &SYSIN DSN! 
&Mem SetC '&SYSIN MEMBER' 
AIF ('&Mem' ne '').Do Mem 
&Mem SetC '(None)' 
~Do Mem DC C'Member: &Mem' 
dC C'Volume: &SYSIN VOLUME' 
MEnd 
My Job  SYSINFO 


&SYSLIB_DSN, &SYSLIB_MEMBER, and &SYSLIB_ VOLUME 


These three symbols identify the origins of the current library member. Their values change 
from member to member. This information can be used to determine reassembly require- 
ments. 


The &SYSLIB_DSN symbol provides the name of the library data set from which each macro 
and COPY file is retrieved. 


The &SYSLIB_MEMBER symbol provides the name of the library member from which this 
macro and COPY file is retrieved. 


The &SYSLIB_VOLUME symbol provides the volume identifier (VOLID) of the library data set 
from which this macro and COPY file is retrieved. 


For example, suppose the LIBINFO macro below is stored in a macro library accessible to 
the assembler at assembly time. (The macro includes a test for a blank member name, 
which should never occur.) 


Macro 
&L LIBINFO 
&L DC C'Library Input: &SYSLIB_DSN' 


&Mem SetC '&SYSLIB_MEMBER' 

AIF ('&Mem' ne '').Do Mem 

MNote 4,'The library member name should not be null.' 
-Do Mem DC C'Member: &Mem' 

DC C'Volume: &SYSLIB_ VOLUME' 

MEnd 


Then the following small test assembly would capture information into the object text of the 
generated program about the macro library. 


My Job LIBINFO 
End 


&SYSNEST 


The &SYSNEST arithmetic variable provides the nesting level at which the current macro 
was invoked (the outermost macro is at level 1). 


For example, a macro might contain tests or MNOTE statements to indicate the nesting 


depth: 
AIF (&SYSNEST LE 50) .0K 
MNOTE 12,'Macro nesting depth exceeds 50. Possible recursion?' 
MEXIT 
OK ANOP 
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&SYSNDX 


The &SYSNDX variable provides a unique value for every macro invocation in the program. 
It may be used as a suffix for symbols generated in the macro, so that they will not “collide” 
with similar symbols generated in other invocations. It is incremented by 1 for every macro 
call in the program. 


For values of &SYSNDX less than or equal to 9999, the value will always be four characters 
long (padded on the left with leading zeros, if necessary). 


Macro 
&L BDisp &Target Branch to non-addressable target 
&L BAS 1,Add&SYSNDX Skip over constant 


OFF&SYSNDX DC Y(&larget-*) Target offset 
Add&SYSNDX AH 1,0ff&SYSNDX Add offset 
BR 1 Branch to target 
MEnd 


&SYSLIST 
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The &SYSLIST variable can be used to access positional parameters on a macro Call 
(whether named or not). &SYSLIST supports a very rich set of sublist and attribute capabili- 
ties, and is therefore quite different from the other system variable symbols. 


&NArgs SETA N'&SYSLIST Number of arguments 
BArg 1 SETC ‘'&SYSLIST(1)' = Argument 1 

&NArgs_ 1 SETA N'&SYSLIST(1) Number of sub-arguments 
&Arg 2 SETC '&SYSLIST(2)' Argument 2 
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System Variable Symbols: Varying Values 


e — &SYSSTMT: next statement number to be processed 


An example, using many System variable symbols: 


C'Assembled by ESYSASH., Version &SYSVER. ' 
ey on &SYSTEM ID.' 
in Job &SYSJ08., Step &SYSSTEP.' 
or on &SYSDATC., at &SYSTIME.. 
C'Opcode table for assembly ee aie OPTABLE..' 
C'&SSSYSPARM value was ''&SYSPARM 
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Variable Symbols Whose Values May Vary Anywhere 


& &SYSSTMT 


The &SYSSTMT symbol provides the number of the next statement to be processed by the 
assembler. Debugger data that depends on the statement number can be generated with 
this variable. For example, suppose we have a macro which inserts information about the 
current statement number into the object code of the program, and sets RO to its address (so 
that a debugger can tell you which statement was identified in some debugging activity). A 
macro like the following might be used: 


Macro 

&L DebugPtN | 

&L BAS 0,*+8 Addr of Statement Number in RO 
DC  AL4(&SYSSTMT) Statement number information 
MEnd 

D DebugPtN 


System Variable Symbols Not Available in DOS/VSE 


There are three system variable symbols supported by High Level Assembler which were 
previously available in Assembler H, but which were not available in the DOS/VSE Assem- 

‘ bler: &SYSDATE, &SYSTIME, and &SYSLOC. (&SYSLOC relies on the availability of the 
LOCTR statement, which was not available in assemblers prior to Assembler H.) 
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Relationships to Previous System Variable Symbols 


Some of the new system variable symbols introduced with High Level Assembler comple- r 
ment and supplement the data provided by system variable available in previous assem- 
blers. 
&SYSDATE and &SYSDATC 
The variable symbol &SYSDATE is available in High Level Assembler and Assembler H, but . 


not in any earlier assemblers. It provides a date in “American” format, without any century 

indication. As such, users in other countries sometimes had to extract and re-compose its 

fields to obtain a date conforming to local custom, convention, or standards. Further, the w 
date could not be placed directly into fields as a sort key, because the year digits were in 

the lowest-order positions. Finally, no century was indicated. 


High Level Assembler’s introduction of the &SYSDATC variable solves all these problems 
very simply. 


&SYSECT and &SYSSTYP 


All previous assemblers have supported the &SYSECT variable to hold the name of the 
enclosing control section at the time a macro was invoked. This allows a macro which needs 
to change control sections (e.g., to declare a DSECT or to create code or data for a different 
CSECT) to resume the original control section on exit from the macro. There was, however, 
a sticky problem: there was no way for the macro to determine what type of control section 
to resume! 


High Level Assembler provides the &SYSSTYP variable to rectify this omission: it provides 
the type of the control section named by &SYSECT. This permits a macro to restore the 
correct previous “control section environment” on exit. 


&SYSNDX and &SYSNEST 


All previous assemblers have supported the &SYSNDX variable symbol, which is incre- 
mented by one for every macro invocation in the program. This permits macros to generate 
unique ordinary symbols if they are needed as “local labels”. Occasionally, in recursively 
nested macro calls, the value of the &SYSNDX variable was used to determine either the 
depth of nesting, or to determine when control had returned to a particular level. 


Alternatively, the programmer could define a global variable symbol of his own, and in each 
macro insert statements to increment that variable on entry and decrement it on exit. This 
technique is both clumsy (because it requires extra coding in every macro) and insecure 
(because not every macro called in a program is likely to be under the programmer’s 
control, particularly IBM-supplied macros). 


High Level Assembler provides the &SYSNEST variable to keep track of the level of macro- 
call nesting in the program. The value of &SYSNEST is incremented globally on each macro 
entry, and decremented on each exit. a 


&SYSTIME and the AREAD Statement 


The &SYSTIME variable symbol is provided by High Level Assembler and Assembler H, but 
not by eariler assemblers. It provides the local time of the start of the assembly in HH/MM 
format. This “time stamp” may not have sufficient accuracy or resolution for some applica- 
tions. 


High Level Assembler provides an extension to the AREAD statement that may be useful if a 
more accurate time stamp is required. The current time can be obtained either in decimal 
or binary format. 
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The macro in the following example captures the clock reading in both decimal and binary 


formats: 


&Lab 


&D 
&B 
&Lab 


Macro 
AREADCLK 

LCLC &D,&B 
Aread CLOCKD 
Aread CLOCKB 


DC C'&D' Decimal Clock 
DC C'&B! Binary Clock 
MEnd 

AREADCLK 
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